Perform Bound/Unbound Action with EntityType Parameters in Power Automate

Published Thursday, March 24, 2022

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 SendEmail, AddMemberList have simple input parameter types (boolean, string, Guid, etc.), but some of the actions like CloseIncident, AddMembersTeam 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 [email protected] 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:

IncidentResolution (incidentresolution EntityType)

subject (Resolution in case resolution dialog)
resolutiontypecode (5 = Problem Solved)
[email protected] (EntitySetName and GUID of Case to be resolved)
statuscode (Status of Case Resolution table, 2 = Closed)

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,
    "[email protected]": "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

CreateAccount (false = do not create an account from the originating lead)
CreateContact (true = create a contact from the originating lead)
CreateOpportunity (create an opportunity from the originating lead)
OpportunityCurrencyId (transactioncurrency EntityType but only reference is required)

transactioncurrencyid (Guid of the Currency row. Since the reference is entity-specific, only primary key is required and @odata.type is not necessary)

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

TemplateId (GUID of the email template to be used)
Regarding (crmbaseentity type entity reference but accepts EntitySetName and GUID of the Regarding row)
Target (crmbaseentity type entity object of an email to be created)

@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)
email_activity_parties (activity party array object for the email sender and recipients)

[email protected] (EntitySetName and GUID of the contact)
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": [{
		"[email protected]": "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": {
    "[email protected]": "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.

Continue to website...