engagements

Creates, updates, deletes, gets or lists an engagements resource.

Overview

Name	engagements
Type	Resource
Id	aws.partnercentral_selling.engagements

Fields

The following fields are returned by SELECT queries:

get_engagement

Name	Datatype	Description
arn	string	The Amazon Resource Name (ARN) of the engagement retrieved. (pattern: <code>arn:.*</code>)
contexts	array	A list of context objects associated with the engagement. Each context provides additional information related to the Engagement, such as customer projects or documents.
created_at	string (date-time)	The date and time when the Engagement was created, presented in ISO 8601 format (UTC). For example: "2023-05-01T20:37:46Z". This timestamp helps track the lifecycle of the Engagement.
created_by	string	The AWS account ID of the user who originally created the engagement. This field helps in tracking the origin of the engagement. (pattern: <code>([0-9]{12}|\w{1,12})</code>)
description	string	A more detailed description of the engagement. This provides additional context or information about the engagement's purpose or scope. (pattern: <code>(?s).{0,255}</code>)
id	string	The unique resource identifier of the engagement retrieved. (pattern: <code>eng-[0-9a-z]{14}</code>)
member_count	integer	Specifies the current count of members participating in the Engagement. This count includes all active members regardless of their roles or permissions within the Engagement.
modified_at	string (date-time)	The timestamp indicating when the engagement was last modified, in ISO 8601 format (UTC). Example: "2023-05-01T20:37:46Z". This helps track the most recent changes to the engagement.
modified_by	string	The AWS account ID of the user who last modified the engagement. This field helps track who made the most recent changes to the engagement. (pattern: <code>([0-9]{12}|\w{1,12})</code>)
title	string	The title of the engagement. It provides a brief, descriptive name for the engagement that is meaningful and easily recognizable. (pattern: <code>(?s).{0,40}</code>)

list_engagements

Name	Datatype	Description
arn	string	The Amazon Resource Name (ARN) of the created Engagement. (pattern: <code>arn:.*</code>)
context_types	array	An array of context types associated with the engagement, such as "CustomerProject" or "Lead". This provides a quick overview of the types of contexts included in the engagement.
created_at	string (date-time)	The date and time when the Engagement was created.
created_by	string	The AWS Account ID of the Engagement creator. (pattern: <code>([0-9]{12}|\w{1,12})</code>)
id	string	The unique identifier for the Engagement. (pattern: <code>eng-[0-9a-z]{14}</code>)
member_count	integer	The number of members in the Engagement.
modified_at	string (date-time)	The timestamp indicating when the engagement was last modified, in ISO 8601 format (UTC). Example: "2023-05-01T20:37:46Z".
modified_by	string	The AWS account ID of the user who last modified the engagement. This field helps track who made the most recent changes to the engagement. (pattern: <code>([0-9]{12}|\w{1,12})</code>)
title	string	The title of the Engagement. (pattern: <code>(?s).{0,40}</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_engagement	select	region		Use this action to retrieve the engagement record for a given EngagementIdentifier.
list_engagements	select	region		This action allows users to retrieve a list of Engagement records from Partner Central. This action can be used to manage and track various engagements across different stages of the partner selling process.
create_engagement_context	insert	region, Catalog, EngagementIdentifier, ClientToken, Type, Payload		Creates a new context within an existing engagement. This action allows you to add contextual information such as customer projects or documents to an engagement, providing additional details that help facilitate collaboration between engagement members.
create_engagement	insert	region, Catalog, ClientToken		The CreateEngagement action allows you to create an Engagement, which serves as a collaborative space between different parties such as AWS Partners and AWS Sellers. This action automatically adds the caller's AWS account as an active member of the newly created Engagement.
update_engagement_context	update	region, Catalog, EngagementIdentifier, ContextIdentifier, EngagementLastModifiedAt, Type, Payload		Updates the context information for an existing engagement with new or modified data.
accept_engagement_invitation	exec	region, Catalog, Identifier		Use the AcceptEngagementInvitation action to accept an engagement invitation shared by AWS. Accepting the invitation indicates your willingness to participate in the engagement, granting you access to all engagement-related data.
reject_engagement_invitation	exec	region, Catalog, Identifier		This action rejects an EngagementInvitation that AWS shared. Rejecting an invitation indicates that the partner doesn't want to pursue the opportunity, and all related data will become inaccessible thereafter.
start_engagement_by_accepting_invitation_task	exec	region, Catalog, ClientToken, Identifier		This action starts the engagement by accepting an EngagementInvitation. The task is asynchronous and involves the following steps: accepting the invitation, creating an opportunity in the partner’s account from the AWS opportunity, and copying details for tracking. When completed, an Opportunity Created event is generated, indicating that the opportunity has been successfully created in the partner's account.
start_engagement_from_opportunity_task	exec	region, Catalog, ClientToken, Identifier, AwsSubmission		Similar to StartEngagementByAcceptingInvitationTask, this action is asynchronous and performs multiple steps before completion. This action orchestrates a comprehensive workflow that combines multiple API operations into a single task to create and initiate an engagement from an existing opportunity. It automatically executes a sequence of operations including GetOpportunity, CreateEngagement (if it doesn't exist), CreateResourceSnapshot, CreateResourceSnapshotJob, CreateEngagementInvitation (if not already invited/accepted), and SubmitOpportunity.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

get_engagement

Use this action to retrieve the engagement record for a given EngagementIdentifier.

SELECT
arn,
contexts,
created_at,
created_by,
description,
id,
member_count,
modified_at,
modified_by,
title
FROM aws.partnercentral_selling.engagements
WHERE region = '{{ region }}' -- required
;

list_engagements

This action allows users to retrieve a list of Engagement records from Partner Central. This action can be used to manage and track various engagements across different stages of the partner selling process.

SELECT
arn,
context_types,
created_at,
created_by,
id,
member_count,
modified_at,
modified_by,
title
FROM aws.partnercentral_selling.engagements
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_engagement_context

Creates a new context within an existing engagement. This action allows you to add contextual information such as customer projects or documents to an engagement, providing additional details that help facilitate collaboration between engagement members.

INSERT INTO aws.partnercentral_selling.engagements (
Catalog,
EngagementIdentifier,
ClientToken,
Type,
Payload,
region
)
SELECT 
'{{ Catalog }}' /* required */,
'{{ EngagementIdentifier }}' /* required */,
'{{ ClientToken }}' /* required */,
'{{ Type }}' /* required */,
'{{ Payload }}' /* required */,
'{{ region }}'
RETURNING
context_id,
engagement_arn,
engagement_id,
engagement_last_modified_at
;

create_engagement

The CreateEngagement action allows you to create an Engagement, which serves as a collaborative space between different parties such as AWS Partners and AWS Sellers. This action automatically adds the caller's AWS account as an active member of the newly created Engagement.

INSERT INTO aws.partnercentral_selling.engagements (
Catalog,
ClientToken,
Title,
Description,
Contexts,
region
)
SELECT 
'{{ Catalog }}' /* required */,
'{{ ClientToken }}' /* required */,
'{{ Title }}',
'{{ Description }}',
'{{ Contexts }}',
'{{ region }}'
RETURNING
arn,
id,
modified_at
;

Manifest

# Description fields are for documentation purposes
- name: engagements
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the engagements resource.
  - name: Catalog
    value: "{{ Catalog }}"
    description: |
      The CreateEngagementRequest$Catalog parameter specifies the catalog related to the engagement. Accepted values are AWS and Sandbox, which determine the environment in which the engagement is managed.
  - name: EngagementIdentifier
    value: "{{ EngagementIdentifier }}"
    description: |
      The unique identifier of the Engagement for which the context is being created. This parameter ensures the context is associated with the correct engagement and provides the necessary linkage between the engagement and its contextual information.
  - name: ClientToken
    value: "{{ ClientToken }}"
    description: |
      The CreateEngagementRequest$ClientToken parameter specifies a unique, case-sensitive identifier to ensure that the request is handled exactly once. The value must not exceed sixty-four alphanumeric characters.
  - name: Type
    value: "{{ Type }}"
    description: |
      Specifies the type of context being created for the engagement. This field determines the structure and content of the context payload. Valid values include CustomerProject for customer project-related contexts. The type field ensures that the context is properly categorized and processed according to its intended purpose.
    valid_values: ['CustomerProject', 'Lead', 'ProspectingResult']
  - name: Payload
    description: |
      Represents the payload of an Engagement context. The structure of this payload varies based on the context type specified in the EngagementContextDetails.
    value:
      CustomerProject:
        Customer:
          Industry: "{{ Industry }}"
          CompanyName: "{{ CompanyName }}"
          WebsiteUrl: "{{ WebsiteUrl }}"
          CountryCode: "{{ CountryCode }}"
        Project:
          Title: "{{ Title }}"
          BusinessProblem: "{{ BusinessProblem }}"
          TargetCompletionDate: "{{ TargetCompletionDate }}"
      Lead:
        Insights:
          LeadReadinessScore: "{{ LeadReadinessScore }}"
        QualificationStatus: "{{ QualificationStatus }}"
        Customer:
          Industry: "{{ Industry }}"
          CompanyName: "{{ CompanyName }}"
          WebsiteUrl: "{{ WebsiteUrl }}"
          Address:
            City: "{{ City }}"
            PostalCode: "{{ PostalCode }}"
            StateOrRegion: "{{ StateOrRegion }}"
            CountryCode: "{{ CountryCode }}"
          AwsMaturity: "{{ AwsMaturity }}"
          MarketSegment: "{{ MarketSegment }}"
        Interactions:
          - SourceType: "{{ SourceType }}"
            SourceId: "{{ SourceId }}"
            SourceName: "{{ SourceName }}"
            Usecase: "{{ Usecase }}"
            InteractionDate: "{{ InteractionDate }}"
            CustomerAction: "{{ CustomerAction }}"
            BusinessProblem: "{{ BusinessProblem }}"
            Contact:
              BusinessTitle: "{{ BusinessTitle }}"
              Email: "{{ Email }}"
              FirstName: "{{ FirstName }}"
              LastName: "{{ LastName }}"
              Phone: "{{ Phone }}"
      ProspectingResult:
        Aws:
          Customer:
            AccountName: "{{ AccountName }}"
            Geo: "{{ Geo }}"
            Region: "{{ Region }}"
            SubRegion: "{{ SubRegion }}"
            Country: "{{ Country }}"
            Industry: "{{ Industry }}"
            SubIndustry: "{{ SubIndustry }}"
            Segment: "{{ Segment }}"
            CompanySize: "{{ CompanySize }}"
            EligiblePrograms:
              - "{{ EligiblePrograms }}"
            PublicProfileSummary: "{{ PublicProfileSummary }}"
          Insights:
            MarketplaceEngagementScore: "{{ MarketplaceEngagementScore }}"
            SolutionScore: "{{ SolutionScore }}"
            SolutionCategory: "{{ SolutionCategory }}"
            SolutionSubCategory: "{{ SolutionSubCategory }}"
          StartTime: "{{ StartTime }}"
          EndTime: "{{ EndTime }}"
          TaskId: "{{ TaskId }}"
          TaskArn: "{{ TaskArn }}"
          TaskName: "{{ TaskName }}"
  - name: Title
    value: "{{ Title }}"
    description: |
      Specifies the title of the Engagement.
  - name: Description
    value: "{{ Description }}"
    description: |
      Provides a description of the Engagement.
  - name: Contexts
    description: |
      The Contexts field is a required array of objects, with a maximum of 5 contexts allowed, specifying detailed information about customer projects associated with the Engagement. Each context object contains a Type field indicating the context type, which must be CustomerProject in this version, and a Payload field containing the CustomerProject details. The CustomerProject object is composed of two main components: Customer and Project. The Customer object includes information such as CompanyName, WebsiteUrl, Industry, and CountryCode, providing essential details about the customer. The Project object contains Title, BusinessProblem, and TargetCompletionDate, offering insights into the specific project associated with the customer. This structure allows comprehensive context to be included within the Engagement, facilitating effective collaboration between parties by providing relevant customer and project information.
    value:
      - Id: "{{ Id }}"
        Type: "{{ Type }}"
        Payload:
          CustomerProject:
            Customer:
              Industry: "{{ Industry }}"
              CompanyName: "{{ CompanyName }}"
              WebsiteUrl: "{{ WebsiteUrl }}"
              CountryCode: "{{ CountryCode }}"
            Project:
              Title: "{{ Title }}"
              BusinessProblem: "{{ BusinessProblem }}"
              TargetCompletionDate: "{{ TargetCompletionDate }}"
          Lead:
            Insights:
              LeadReadinessScore: "{{ LeadReadinessScore }}"
            QualificationStatus: "{{ QualificationStatus }}"
            Customer:
              Industry: "{{ Industry }}"
              CompanyName: "{{ CompanyName }}"
              WebsiteUrl: "{{ WebsiteUrl }}"
              Address:
                City: "{{ City }}"
                PostalCode: "{{ PostalCode }}"
                StateOrRegion: "{{ StateOrRegion }}"
                CountryCode: "{{ CountryCode }}"
              AwsMaturity: "{{ AwsMaturity }}"
              MarketSegment: "{{ MarketSegment }}"
            Interactions:
              - SourceType: "{{ SourceType }}"
                SourceId: "{{ SourceId }}"
                SourceName: "{{ SourceName }}"
                Usecase: "{{ Usecase }}"
                InteractionDate: "{{ InteractionDate }}"
                CustomerAction: "{{ CustomerAction }}"
                BusinessProblem: "{{ BusinessProblem }}"
                Contact:
                  BusinessTitle: "{{ BusinessTitle }}"
                  Email: "{{ Email }}"
                  FirstName: "{{ FirstName }}"
                  LastName: "{{ LastName }}"
                  Phone: "{{ Phone }}"
          ProspectingResult:
            Aws:
              Customer:
                AccountName: "{{ AccountName }}"
                Geo: "{{ Geo }}"
                Region: "{{ Region }}"
                SubRegion: "{{ SubRegion }}"
                Country: "{{ Country }}"
                Industry: "{{ Industry }}"
                SubIndustry: "{{ SubIndustry }}"
                Segment: "{{ Segment }}"
                CompanySize: "{{ CompanySize }}"
                EligiblePrograms: "{{ EligiblePrograms }}"
                PublicProfileSummary: "{{ PublicProfileSummary }}"
              Insights:
                MarketplaceEngagementScore: "{{ MarketplaceEngagementScore }}"
                SolutionScore: "{{ SolutionScore }}"
                SolutionCategory: "{{ SolutionCategory }}"
                SolutionSubCategory: "{{ SolutionSubCategory }}"
              StartTime: "{{ StartTime }}"
              EndTime: "{{ EndTime }}"
              TaskId: "{{ TaskId }}"
              TaskArn: "{{ TaskArn }}"
              TaskName: "{{ TaskName }}"

UPDATE examples

update_engagement_context

Updates the context information for an existing engagement with new or modified data.

UPDATE aws.partnercentral_selling.engagements
SET 
Catalog = '{{ Catalog }}',
EngagementIdentifier = '{{ EngagementIdentifier }}',
ContextIdentifier = '{{ ContextIdentifier }}',
EngagementLastModifiedAt = '{{ EngagementLastModifiedAt }}',
Type = '{{ Type }}',
Payload = '{{ Payload }}'
WHERE 
region = '{{ region }}' --required
AND Catalog = '{{ Catalog }}' --required
AND EngagementIdentifier = '{{ EngagementIdentifier }}' --required
AND ContextIdentifier = '{{ ContextIdentifier }}' --required
AND EngagementLastModifiedAt = '{{ EngagementLastModifiedAt }}' --required
AND Type = '{{ Type }}' --required
AND Payload = '{{ Payload }}' --required
RETURNING
context_id,
engagement_arn,
engagement_id,
engagement_last_modified_at;

Lifecycle Methods

accept_engagement_invitation

Use the AcceptEngagementInvitation action to accept an engagement invitation shared by AWS. Accepting the invitation indicates your willingness to participate in the engagement, granting you access to all engagement-related data.

EXEC aws.partnercentral_selling.engagements.accept_engagement_invitation 
@region='{{ region }}' --required 
@@json=
'{
"Catalog": "{{ Catalog }}", 
"Identifier": "{{ Identifier }}"
}'
;

reject_engagement_invitation

This action rejects an EngagementInvitation that AWS shared. Rejecting an invitation indicates that the partner doesn't want to pursue the opportunity, and all related data will become inaccessible thereafter.

EXEC aws.partnercentral_selling.engagements.reject_engagement_invitation 
@region='{{ region }}' --required 
@@json=
'{
"Catalog": "{{ Catalog }}", 
"Identifier": "{{ Identifier }}", 
"RejectionReason": "{{ RejectionReason }}"
}'
;

start_engagement_by_accepting_invitation_task

This action starts the engagement by accepting an EngagementInvitation. The task is asynchronous and involves the following steps: accepting the invitation, creating an opportunity in the partner’s account from the AWS opportunity, and copying details for tracking. When completed, an Opportunity Created event is generated, indicating that the opportunity has been successfully created in the partner's account.

EXEC aws.partnercentral_selling.engagements.start_engagement_by_accepting_invitation_task 
@region='{{ region }}' --required 
@@json=
'{
"Catalog": "{{ Catalog }}", 
"ClientToken": "{{ ClientToken }}", 
"Identifier": "{{ Identifier }}", 
"Tags": "{{ Tags }}"
}'
;

start_engagement_from_opportunity_task

Similar to StartEngagementByAcceptingInvitationTask, this action is asynchronous and performs multiple steps before completion. This action orchestrates a comprehensive workflow that combines multiple API operations into a single task to create and initiate an engagement from an existing opportunity. It automatically executes a sequence of operations including GetOpportunity, CreateEngagement (if it doesn't exist), CreateResourceSnapshot, CreateResourceSnapshotJob, CreateEngagementInvitation (if not already invited/accepted), and SubmitOpportunity.

EXEC aws.partnercentral_selling.engagements.start_engagement_from_opportunity_task 
@region='{{ region }}' --required 
@@json=
'{
"Catalog": "{{ Catalog }}", 
"ClientToken": "{{ ClientToken }}", 
"Identifier": "{{ Identifier }}", 
"AwsSubmission": "{{ AwsSubmission }}", 
"Tags": "{{ Tags }}"
}'
;