Dynamics CRM Scripting for Business Process Flows

Dynamics CRM 365/ Dynamics CRM 2015/ CRM 2016 lets the developers interact with the business process flows by writing client-side scripts. Business Process flow actions can be performed programmatically by making use of the methods under Xrm.Page.data.process and Xrm.Page.ui.process namespaces.

To interact with the business process flow, in addition to the entity form events, two new events onStageChange() and onStageSelected() event are provided by the client API.

Below is the list of methods for tapping into the  Business Process Flow capability.

Method Description Implementation
Process Methods
getEnabledProcesses –  Executes asynchronously

–  Retrieves the information about all the business process flows enabled for the entity

–  Returns a dictionary object where Id is the key and Name is the value

//GetEnabledProcesses

Xrm.Page.data.process.getEnabledProcesses(function (processes) {

for (var processId in processes) {

alert(“Id:” + processId + “, Name:” + process[processId]);

}

});

setActiveProcess –  Executes asynchronously

–  Sets the business process flow for the entity passed as a parameter

–  Returns the status of the operation (success or invalid)

// Set Active Process

Xrm.Page.data.process.setActiveProcess(processId, function (status) {

alert(status);

});

getActiveProcess –  Retrieves the information about the active business process flow for the entity

–   Returns an object containing the data for the active process

var id, processName, stageCount;

var activeProcess = Xrm.Page.data.process.getActiveProcess();

if (activeProcess != null) {

// Get Process Id

id = activeProcess.getId();

// Get Process Name

processName = activeProcess.getName();

// Get Process stage count

stageCount = activeProcess.getStages().getLength();

}

setDisplayState –  Displays the business process flow as expanded or collapsed

–  Display state is passed as a string parameter to the function

if (Xrm.Page.ui.process.getDisplayState() == “collapsed”) {

// Set the display as expanded

Xrm.Page.ui.process.setDisplayState(“expanded”);

}

else {

// Set the display as collapsed

Xrm.Page.ui.process.setDisplayState(“collapsed”);

}

setVisible –  Shows or hides the business process flow

–  Boolean parameter to show (true) or hide (false) the process

if (!Xrm.Page.ui.process.getVisible()) {

// Show the business process flow

Xrm.Page.ui.process.setVisible(true);

}

else {

// Hide the business process flow

Xrm.Page.ui.process.setVisible(false);

}

Stage Methods
getStages –  Retrieves the information about a specific stage in the process identified by the index value

–  Returns an object containing the data related to a particular stage in a process

var stageObj,stageId, stageName, stageEntityName, stageCategory, stageStatus;

var activeProcess = Xrm.Page.data.process.getActiveProcess();

if (activeProcess != null) {

// Get the First stage object of the process

stageObj = activeProcess.getStages().get(0);

// Get Stage Id

stageId = stageObj.getId();

// Get Stage Name

stageName = stageObj.getName();

// Get Stage Entity name

stageEntityName = stageObj.getEntityName();

// Get Stage Category

stageCategory = stageObj.getCategory().getValue(); // – integer value of the stage

// Get Stage Status

stageStatus = stageObj.getStatus(); // – active/inactive

}

getActiveStage –  Returns an object representing the current active stage of the process var activeStage;

// Get Active Stage object

activeStage = Xrm.Page.data.process.getActiveStage();

setActiveStage –  Executes asynchronously

–  Sets a completed stage for the current entity as the active stage

// Sets the Stage identified by the id as the active stage

Xrm.Page.data.process.setActiveStage(stageId, function (data) {

alert(data);

});

getActivePath –  Retrieves a collection of stages currently in the active path.

–  Contains information for completed stages, current active stage as well as predicted future stages based on the data on the current record and branching rules for the process

 

// Get Active Path

var activePath = Xrm.Page.data.process.getActivePath();

if (activePath != null) {

activePath.forEach(function (stage, n) {

alert(” Stage Index: ” + n + “\n Entity: ” + stage.getEntityName() + “\n StageId: ” + stage.getId() + “\n Status: ” + stage.getStages());

 

})

 

}

Step Methods
getSteps –  Retrieves the information of all the steps in a particular stage of the process var stepCollection, stepCount, stepObj,stepName,stepAttributeName,isStepReq,stepType;

var activeStage = Xrm.Page.data.process.getActiveStage();

if (activeStage) {

 

// Get Step count

stepCount = activeStage.getSteps().getLength();

// Get the Steps of a stage

stepCollection = activeStage.getSteps();

// Get the First Step object of the stage

stepObj = activeStage.getSteps().get(0);

// Get the Step Name

stepName = stepObj.getName();

// Get the Step Attribute name

stepAttributeName = stepObj.getAttribute();

// Check whether the Step is required

isStepReq = stepObj.isRequired();

// Get the Step type

stepType = stepObj.getStepType();

}

Navigation Methods
moveNext –  Progresses the process to the next stage

–  Works only when the selected stage and the active stage are the same

–  Triggers the onStageChange event

–  Returns the status in a callback function indicating the operation status (success, crossEntity, end, invalid)

// Move Next

Xrm.Page.data.process.moveNext(function (status) {

if(status == “success”)

alert(“Moved to next stage”);

});

movePrevious –  Moves the process to the previous stage

–  Works only when the selected stage and the active stage are the same

–  Triggers the onStageChange event

–  Returns the status of the operation

// Move Previous

Xrm.Page.data.process.movePrevious(function (status) {

if(status == “success”)

alert(“Moved to previous stage”);

});

 

Event Handler Methods
addOnStageChange –  Adds a function as an event handler for the onStageChange event

–  Event handler function executes when Next or Previous button is clicked on the process UI

// Add onStageChange event handler

Xrm.Page.data.process.addOnStageChange(stageChanged);

 

function stageChanged(execContext)

{

// Get direction

var direction = execContext.getEventArgs().getDirection();

// Get the current stage object

var currentStage = execContext.getEventArgs().getStage();

}

removeOnStageChange –  Removes a function as an event handler for the onStageChange event // Remove onStageChange event handler

Xrm.Page.data.process.removeOnStageChange(stageChanged);

addOnStageSelected –  Adds a function as an event handler for the onStageSelected event

–  Event handler function executes whenever a stage of an business process flow is selected

// Add onStageSelected event handler

Xrm.Page.data.process.addOnStageSelected(stageSelected);

 

function stageSelected(execContext)

{

// Gets the current stage

var currentStage = execContext.getEventArgs().getStage();

}

removeOnStageSelected –  Removes a function as an event handler for the onStageSelected event // Remove onStageSelected event handler

Xrm.Page.data.process.removeOnStageChange(stageSelected);

Hope you will find it useful!

Cheers
Swaroop
Adisys Engineering Team

Advertisements

Introducing Transactions with Dynamics CRM 2015

 

We always wanted a transactions capabilities when you are performing business logic in enterprise applications, given the complexity of the application, integration or business rules. Transactions gives full capability to manage application behavior.

In order to implement transactions through windows or web based applications we used to write our own logic to roll back the operations in case of any business logic failure or change in data status.

We can take the example of my project where I wanted to rollback all operations in case of payment failure while buying order through online portal. In case of payment failure, I wrote my own logic to rollback records.

In Dynamics CRM 2015 update 1, as transactions been introduced, I was able to use ExecuteTransactionRequest, this is  helpful to maintain integrity during the context of transactions.

We can execute multiple operations in single database transaction so that either all operations will be executed successfully or none (revert back).

You need to add the reference to Microsoft.Xrm.Sdk dll.. We can provide collection of Organization request as given in below example.  I have added 3 requests to the collection. ExecuteTransactionRequest takes request collections as a parameter

public static void PerformTransactionOperation(OrganizationService service)
{
var request = new ExecuteTransactionRequest()
{
Requests = new OrganizationRequestCollection()
};

var account = new Entity(“account”);
account[“name”] = “Account Test”;
var createRequest = new CreateRequest() { Target = account };
request.Requests.Add(createRequest);

RetrieveRequest retReq = new RetrieveRequest() { Target = new EntityReference(“account”, new Guid(“B6F79317-5E8E-E511-80E7-3863BB2E1390”)) };

retReq.ColumnSet = new ColumnSet(“name”);
request.Requests.Add(retReq);
Entity accToUpdate = new Entity(“account”);

accToUpdate.Id = new Guid(“B6F79317-5E8E-E511-80E7-3863BB2E1390”);
var updateRequest = new UpdateRequest() { Target = accToUpdate };
request.Requests.Add(updateRequest);
try
{
var respTrans = (ExecuteTransactionResponse)service.Execute(request);
foreach (var response in respTrans.Responses)
{
switch (response.ResponseName.ToUpper())
{
case “CREATE”:
var createResponse = (CreateResponse)response;
Console.WriteLine(“Account created: {0}”, createResponse.id);
break;

case “UPDATE”:
var updateResponse = (UpdateResponse)response;
break;

case “DELETE”:
var deleteResponse = (DeleteResponse)response;
break;

case “SETSTATE”:

var setstateResponse = (SetStateResponse)response;

break;

case “RETRIEVE”:
var retResponse = (RetrieveResponse)response;
break;
}}}
catch (FaultException<OrganizationServiceFault> ex)
{
ExecuteTransactionFault fault = (ExecuteTransactionFault)ex.Detail;
}}

It will be executed in the same order as it was added to collection.

In our case we got 3 responses for each request. In my code, I am checking the Response name and accordingly performing each operation.

If you want to know the exact request that was failed, you can check the FaultedRequestIndex as given below. It will tell you the index number of the request that was failed.

Few important points to Note:

  • An ExecuteMultipleRequest may have multiple ExecuteTransactionRequest instances.
  • An ExecuteTransactionRequest instance may not contain a ExecuteMultipleRequest or ExecuteTransactionRequest.
  • It has same limit as ExecuteMultipleRequest. Maximum batch size could be 1000. You can have maximum 1000 Requests in a batch.
  • CRM online can have maximum 2 Concurrent batch request.
  • If you have more than 1000 Requests you have to split the requests in batches.

Hope this Post is helpful. I would love to hear your suggestions.

Happy CRMing!!!!!!!!
Thank you,
Kalim Ansar
Adisys Corporation

Set Custom Help URLs in Dynamics CRM Online 2015

Set Custom Help URL CRM Online 2015
Custom Help URL is another exciting feature in Dynamics CRM 2015. Administer can simply enable and configure the URL at both Global Level and Entity Level.

There are 3 kind of Help URL:

  • Build-in CRM Help (Default)
  • Global Level Custom Help
  • Entity Level Custom Help (Support both OOB entity and Custom Entity)

1)    Build-in CRM Help:

Below is the built-in CRM Online Help hosted on Microsoft website. User will be navigated to this online knowledge base center by default after clicking on Help link.

Dynamics CRM Help #1

Dynamics CRM Help #1

Dynamics CRM Help #1

 

 

 

 

 

 

2)     Custom URL at Global Level

System administrator can configure Global custom Help URL. Go to Settings -> Administration -> System Settings -> General:

Dynamics CRM Help #2

Dynamics CRM Help #2

 

 

Global Custom Help URL link in CRM:

Dynamics CRM Help #3

Dynamics CRM Help #3

 

3)     Entity Level Custom Help URL

To enable and configure the custom help URL on a specific entity form, administrator can go to Entity Customization:

Dynamics CRM Help #4

Dynamics CRM Help #4

 

Help Link on Entity form:

Dynamics CRM Help #5

Dynamics CRM Help #5

Hopefully you will find it useful!
Thank you,
Zhe Chen
Adisys Corporation

Set Hierarchy Security in Dynamics CRM Online

We have a requirement to allow the manager to view and update the records owned by the direct report.

In Dynamics CRM 2015 introduced hierarchy security model in CRM 2015 Update 1 which make it super easy to implement this kind security requirement.

Hierarchy security is an extension to the existing security models that use business units, security roles, sharing, and teams. There are two security options in Hierarchy Security Model:

  • Management Chain, based on the direct reporting structure and the hierarchy depth
  • Position Hierarchy, based on the defined job positions and the hierarchy depth
Dynamics CRM 2015 Hieararchy Security

Dynamics CRM 2015 Hieararchy Security

 

A user can be assigned to one position and hence get a Read, Write, Update, Append, AppendTo access to the lower positions’ data in the direct ancestor path. The non-direct higher positions, have Read-only access to the lower positions’. Following is a sample of the Position Hierarchy structure defined in CRM.

In this organization, CEO has full access to the data owned by HR Managers, Sales Managers and Service Managers. Sales managers has the full access to the data owned by Sales. Once you have position hierarchy defined in system then administrator can easily assign the user for the position to get the access accordingly.

Dynamics CRM 2015 Hierarchy Security #2

Dynamics CRM 2015 Hierarchy Security #2

Hopefully you find it useful!
Thank you,
Zhe Chen
Adisys Corporation

Time-Zone Independent Date Field in Dynamics CRM Online 2015

Time-Zone Independent Date Field in CRM Online 2015 Update

 Prior to CRM Online 2015 update 1, CRM saves date in UTC format in Database and show the local date time to user based on the login user’s time zone configuration. It works perfect if you have users around the world. However it might cause some confusions for below scenarios:

  • The exact date not depend on the time zone. Ex: birthday, Anniversary
  • The exact date time not depend on time zone. Ex: Hotel Check in/out Date and time
  • Data migration
  • System/Data Integration

With the latest CRM Online 2015 update release, Microsoft introduces the DateTimeBehavior property to define whether to store date and time values with or without time zone information. Followings are the definition for these three Behavior:

 

CRM Online Time Settings

CRM Online Time Settings

 

Member name and value Description
UserLocal
  • Stores the date and time value as UTC value in the system.
  • The retrieve operation returns the UTC value.
  • The update operation converts the UTC value to the current user’s time zone value, and then stores the updated value as is or as the equivalent UTC value depending on the kind (DateTimeKind) of the value specified for update. If the specified value is of UTC kind, it’s stored as is. Otherwise, the UTC-equivalent value is stored.
  • Retrieving the formatted value converts from UTC to the user’s current time zone based on the time zone and locale setting of the user.
  • For the OData endpoint, the attribute is exposed as DateTimeOffset.
  • This behavior is used for system attributes like CreatedOn and ModifiedOn, and cannot be changed. You should use this behavior for custom attributes where you want to store date and time values with the time zone information.
DateOnly
  • Stores the actual date value with the time value as 12:00 AM (00:00:00) in the system.
  • For the retrieve and update operations, no time zone conversion is performed, and the time value is always 12 AM (00:00:00).
  • Retrieving the formatted value displays the date value without any time zone conversion.
  • For the OData endpoint, the attribute is exposed as DateTimeOffset.
  • This behavior should be used for custom attributes that store birthdays and anniversaries, where the time information is not required.
TimeZoneIndependent
  • Stores the actual date and time values in the system regardless of the user time zone.
  • For the retrieve and update operations, no time zone conversion is performed, and actual date and time values are returned and updated respectively in the system regardless of the user time zone.
  • Retrieving the formatted value displays the date and time value (without any time zone conversion) based on the format as specified by the current user’s time zone and locale setting.
  • For the OData endpoint, the attribute is exposed as DateTimeOffset.
  • This behavior should be used for attributes that store information such as check in and check out time for hotels.

Hopefully you find it useful!
Thank you,
Zhe Chen