Perform Bound/Unbound Action with EntityType Parameters in Power Automate

In this post, I will explain how you can populate the entity (or table) type input parameters for some of the bound/unbound actions in cloud flows.

When the input parameters are not simple data types (such as string, boolean, etc.), It can be a bit tricky to populate. Some of the entity type parameters are expecting an entity object, with column values to be created as a new row but some of the entity type parameters are expecting an entity reference (Primary Key and @odata.type). I briefly explained about it in my last blog post but I believe this topic deserves a dedicated blog post on it’s own.

Actions

Actions in Microsoft Dataverse represent re-usable operations you can perform using the Web API and you can call those actions in cloud flows using the Perform a bound action / Perform an unbound action. When the actions are called from cloud flows, it is always recommended to check the Web API Action Reference documentation to understand the parameters required by the action. Some of the actions like SendEmailAddMemberList have simple input parameter types (boolean, string, Guid, etc.), but some of the actions like CloseIncidentAddMembersTeam require parameters of entity type like incidentresolution, crmbaseentity, etc. Let’s have a look at how you can populate the EntityType parameters for different actions.

💡 Tip

If you are not sure whether you need to populate the entity object or entity reference in the parameter, do a quick web search for the action name with double quotes to find some examples provided by the community. (e.g. "AddMemberList""CloseIncident", etc. Andrew Butenko has answered some of actions in the community forum and he has compiled WebApi examples in his blog (which can be referenced to compose the JSON object of Action Parameters).

🔗 CloseIncident Action (sample for entity type parameter)

CloseIncident action has two parameters, IncidentResolution and Status. But when I chose that action in Perform an unbound action, the IncidentResolution is not rendered properly by the flow designer because it is expecting the EntityType parameter. The EntityType parameter of the CloseIncident action is expecting the Case Resolution object with the column values and the action will create the new row of Case Resolution and close the related case as Resolved.
It shows some columns from the Case Resolution Activity instead of one single IncidentResolution parameter as specified in the documentation but not all columns from the Case Resolution tables are available either.

When I populated the important columns of the Case Resolution and ran the flow, it failed with the error below because the flow step was trying to set the value directly to _incidentid_value property instead of incidentid@odata.bind navigation property.
CRM do not support direct update of Entity Reference properties, Use Navigation properties instead.

To populate the navigation property, you will have to use the custom item hack as mentioned in my last post to populate the Action Name instead of selecting from the list. The expression of the custom value would be trim('CloseIncident'). When the flow designer does not recognise the action name, the Action Parameters will become one single multiline textbox and you need to populate it with a JSON object. You cannot get the exact JSON format but you can populate some of the input parameters and peek code to get some idea about how to compose your JSON object.

These are the parameter values populated:
  1. IncidentResolution (incidentresolution EntityType)
    1. subject (Resolution in case resolution dialog)
    2. resolutiontypecode (5 = Problem Solved)
    3. incidentid@odata.bind (EntitySetName and GUID of Case to be resolved)
    4. statuscode (Status of Case Resolution table, 2 = Closed)
  2. Status (statuscode of Case table, 5 = Problem Solved)
The above screenshot shows how the action will look like and below is the sample JSON object. Replace the GUID "e515f881-1bf1-4ebd-9290-92429bbb1c80" with the GUID of the Case that needs to be resolved.
{
  "IncidentResolution": {
    "subject": "Test Resolution",
    "resolutiontypecode": 5,
    "incidentid@odata.bind": "incidents(e515f881-1bf1-4ebd-9290-92429bbb1c80)",
    "statuscode": 2
  },
  "Status": 5
}

The parameters for WinQuote action is also similar and you can find out more details in my last blog post. The parameters for WinOpportunity can be found here.

🔗 QualifyLead Action (sample for entity-specific reference parameter)

QualifyLead action has quite a number of parameters and the mandatory parameters are all simple data types (boolean, integer). But if you need to specify the currency to use for the generated opportunity, the OpportunityCurrencyId parameter is transactioncurrency EntityType. Even though OpportunityCurrencyId parameter is EntityType, it is not expecting the Currency object, only the EntityReference (or just Primary Key is enough). Don't worry, you don't have to create a new currency for each lead that you are qualifying. You can ignore the transactioncurrency parameters and just populate the Action name with custom value to show the Action Parameters.

One more thing to be mindful when you use the custom item hack to populate the Action Name is that the action name to be used in the expression may not be exactly as what you see in the documentation or the drop-down selection. For this instance, if you just use the action name 'QualifyLead', you will get the following error.
Resource not found for the segment 'QualifyLead'
You will also notice that from the subtitle of the option if you are using a new expression builder from the experimental features.

The complete action name would be trim('Microsoft.Dynamics.CRM.QualifyLead') and you can check it out using peek code for the proper actionName parameter.

These are the parameter values populated
  1. CreateAccount (false = do not create an account from the originating lead)
  2. CreateContact (true = create a contact from the originating lead)
  3. CreateOpportunity (create an opportunity from the originating lead)
  4. OpportunityCurrencyId (transactioncurrency EntityType but only reference is required)
    1. transactioncurrencyid (Guid of the Currency row. Since the reference is entity-specific, only primary key is required and @odata.type is not necessary)
  5. Status (statuscode of Lead, 3 = Qualified)
The above screenshot shows how the action will look like and below is the sample JSON object. Replace the GUID "2E8C917E-3520-EB11-A813-000D3A799D17" with the GUID of the Currency to be used for the generated opportunity.
{
  "CreateAccount": false,
  "CreateContact": true,
  "CreateOpportunity": true,
  "OpportunityCurrencyId": {
    "transactioncurrencyid": "2E8C917E-3520-EB11-A813-000D3A799D17"
  },
  "Status": 3
}

🔗 AddMembersTeam Action (sample for entity reference parameter with different primary key)

For some reason, AddMembersTeam action renders the Members parameter properly without showing the column names from User table even though the parameter is systemuser EntityType. That is probably because the parameter is of array type and the flow designer can render the array type parameters well. Just like the OpportunityCurrencyId parameter in QualifyLead action, the value for Members parameter is an array of objects with primary key (GUID) of the user and no other properties are required.
If you need to add more users dynamically (e.g. by looping through the output of List Records action, you can use Switch to input entire array option at the top right corner of the Members property (stay tuned for my next post for more details). Above screenshot is how the action will look like and you might notice that the property name of the systemuser GUID is "ownerid" instead of "systemuserid". This is because the Primary Key of the User EntityType is "ownerid" as mentioned in the documentation.

🔗 SendEmailFromTemplate Action (sample for crmbaseentity EntityType parameter)

For some actions like SendEmailFromTemplate, the EntityType parameter is generic crmbaseentity because Regarding lookup of the e-mail message can be of any table type. In that case, @odata.type (entity logical name with "Microsoft.Dynamics.CRM." prefix) is required to define the type of the table.
These are the parameter values populated
  1. TemplateId (GUID of the email template to be used)
  2. Regarding (crmbaseentity type entity reference but accepts EntitySetName and GUID of the Regarding row)
  3. Target (crmbaseentity type entity object of an email to be created)
    1. @odata.type (the type of the entity. Double @@ is required as an escape character because single leading@ would cause the following error message when the flow is saved)
    2. email_activity_parties (activity party array object for the email sender and recipients)
      1. partyid_contact@odata.bind (EntitySetName and GUID of the contact)
      2. participationtypemask (2 = To recipient)
Request to XRM API failed with error: 'Message: Flow client error returned with status code "BadRequest" and details "{"error":{"code":"TemplateValidationError","message":"The power flow's logic app flow template was invalid. Unable to parse template language expression 'odata.type': expected token 'LeftParenthesis' and actual 'Dot'."}}". Code: 0x80060467 InnerError: '.

The above screenshot shows how the action will look like and below is the sample JSON object. Replace the GUID "7816B01C-EFA8-4396-8BA5-0B6B72DA5C08" with the GUID of the email template to be used. Replace "contacts(8da6e5b9-88df-e311-b8e5-6c3be5a8b200)" with the regarding object and the email recipient.
{
	"@@odata.type": "Microsoft.Dynamics.CRM.email",
	"email_activity_parties": [{
		"partyid_contact@odata.bind": "contacts(8da6e5b9-88df-e311-b8e5-6c3be5a8b200)",
		"participationtypemask": 2
	}]
}
You can read more details about SendEmailFromTemplate action at the Inogic blog.

🔗 msdyn_AssignResourcesForTask Action

msdyn_AssignResourcesForTask action is used to assign a resource to the project task in Project Operations. It also has a similar crmbaseentity parameter, TeamCollection, which accepts the array of entity references just like the Regarding parameter of SendEmailFromTemplate Action. Context parameter is nullable and it is not required.

This is the example of assigning one Project Team Member for a task. For entity reference parameter, msdyn_projectteams needs to be the plural EntitySetName with 's'. You will need to replace the GUID of the Row ID with the GUID of the Project Task and GUID after msdyn_projectteams with the GUID of the Project Team Member. If the Resource (bookableresource) is not yet a team member for a project, you have to create a row in Project Team Member first.

This is an example of assigning multiple Project Team Members for a task in a single action. You can build an array of JSON object for TeamCollection in a loop.

🔗 WinOpportunity Action

WinOpportunity action has two parameters, OpportunityClose and Status.
The above screenshot shows how the action will look like and below is the sample JSON object. Replace the GUID "be0d0283-5bf2-e311-945f-6c3be5a8dd64" with the GUID of the Opportunity that needs to be closed as Won.
{
  "OpportunityClose": {
    "opportunityid@odata.bind": "opportunities(be0d0283-5bf2-e311-945f-6c3be5a8dd64)",
    "actualrevenue": 10000000,
    "statuscode": 2,
    "actualend": "2021-05-10T12:00:00Z",
    "description": "Test Opportunity Close"
  },
  "Status": 3
}

Summary

Populate the EntityType parameters in bound/unbound actions requires more in-depth knowledge about the parameter values and advanced knowledge of JSON. Some of the entity type parameters are expecting an entity object with column values while some are expecting an entity reference (Primary Key and @odata.type). Some of the actions require custom item hack to populate the Action Name using expression just to populate the Action Parameters input with a JSON object.

Comments

  1. again a great Job fromyou Linn. I am not any more surprising with such an amazing article beacuse I think so, it is your daily life

    ReplyDelete
    Replies
    1. Thanks for your encouring comment, Necdet. 😊

      Delete
  2. Hello, thank you for this great blog.
    I'm trying to add an Action (AddToQueue) at the end of a Flow after migrating with the ARC & SLA Migration feature without success.
    I think i have some issue with parameters of the action.
    Any idea to add "A Perform a Bound Action" with AddToQueue ?

    ReplyDelete
    Replies
    1. Hi Fabrice,

      Apologies for the late reply. Some of the Actions are not working well in the cloud flows and AddToQueue is one of them. The workaround solution is to implement the Custom API wrapper for the operation with the parameters you need.

      You can also install the Dataverse PowerAutomate Helpers managed solution from the following repo and use the sample_AddToQueue action rather than the OOTB AddToQueue action.
      https://github.com/JimDaly/DataversePowerAutomateHelpers

      Delete
  3. Hello Linn,
    thank you for this great blog article. Really helped to get a bound action with an entity reference to work.
    Thanks!

    ReplyDelete
    Replies
    1. Awesome... I am glad to know that it helped.

      Delete
  4. Hi Linn

    Thanks for this post - really helpful to solve our requirement for automatically qualifying leads!

    ReplyDelete
  5. Hi Linn,

    Thank you for sharing. Do you have a similar post on how to retrieve segment members by performing an unbound action using power automate?

    ReplyDelete
    Replies
    1. @Julien, I don't have any post about retrieving segment members. Which unbound action are you going to use to retrieve segment members? msdyncrm_LoadSegmentMembers?

      Delete
  6. Thanks! This post gave me an idea on how to help colleague with similar question!

    ReplyDelete
    Replies
    1. Thanks for the comment, Andrew. I am glad to know that this post is useful for your colleague.

      Delete
  7. Thanks for sharing! Will it be possible to trigger a specific customer journey by performing an unbound action using Power Automate? If so, what might be the action name?

    ReplyDelete
    Replies
    1. In addition to the above, if there is no unbound action to trigger a customer journey. Can we publish it using Power Automate? Hence, it will be flagged to Go-Live and the journey will start automatically?

      Delete
    2. There's no unbound action to trigger a customer journey but you can publish it using a cloud flow by updating the Status = Active and Status Reason = Going live.
      https://www.screencast.com/t/6nWoRqq4g2S5

      Just make sure to click "Check for errors" after making final changes to your customer journey and ready to go live. Or else, you'll get the error below.
      "Please validate the customer journey prior publishing it.,"

      Delete
  8. Hello,

    I am trying something similar where I am trying to populate the TeamCollection Item within the msdyn_assignresourcesfortask based on the Project Tasks action.

    Any help would be gratefully received.

    Thanks

    Lee

    ReplyDelete
    Replies
    1. Updated the post with the example for msdyn_AssignResourcesForTask Action. Check it out.
      https://linnzawwin.blogspot.com/2020/12/perform-boundunbound-action-with.html#msdyn_AssignResourcesForTask

      Delete
  9. Can you give an example of a BulkDelete on a Custom Entity?

    ReplyDelete

Post a Comment

Popular Posts