Dynamics CRM - Create session

Declaration

<AMDYNAMICSCRM ACTIVITY="create_session" 
PROTOCOL="text (options)" 
SERVER="text" USERNAME="text" PASSWORD="text 
(encrypted)" DOMAIN="text" ORGANIZATION="text" 
AUTODISCOVER="yes/no" DISCOVERYURI="text" 
ORGANIZATIONURI="text" HOMEREALMURI="text" 
AUTHTYPE="text (options)" TIMEOUT="number" 
PROXYTYPE="text (options)" PROXYSERVER="text" 
PROXYPORT="number" PROXYUSERNAME="text" 
PROXYPASSWORD="text (encrypted)" SESSION="text" />

Description: Creates a unique session which can be used to associate subsequent Dynamics CRM steps allowing a single task the ability to execute numerous Dynamics CRM operations simultaneously.

IMPORTANT: To function properly, this activity requires a Microsoft Dynamics CRM System Administrator or System Customizer security role or equivalent permissions.

Practical Usage

Commonly used as a means of organizing and encapsulating a collection of related activities required to accomplish a particular task or process. The use of sessions can ensure consistency and eliminate redundancy.

Connection Parameters

Property

Type

Required

Default

Markup

Description

Server (protocol)

Text (options)

Yes

HTTPS

PROTOCOL="HTTP"

Specifies the protocol used to connect to the Dynamics CRM server. The available options are:

  • HTTPS (default) - Hypertext Transfer Protocol Secure, which adds security capabilities of SSL/TLS to standard HTTP communications.

  • HTTP - Hypertext Transfer Protocol

Server

Text

Yes

(Empty)

SERVER="crm.dynamics.com"

The URL or IP address of the Dynamics CRM server to establish a connection with. If entering a URL, the port is optional if it is HTTP over port 80 or HTTPS over port 443. (e.g., crm-server:port). The server URL is typically in the format of:

http://crm-server:port/organization-name

Or for Microsoft Dynamics CRM Online:

https://organization-name.crm.dynamics.com

Username or Windows Live ID

Text

Yes

(Empty)

  1. USERNAME="jsmith"

  2. USERNAME="jsmith@live-int.com"

The username of the account used to establish a Dynamics CRM server connection. The format for this value is specific to the authentication type: domain\username for AD and SPLA authentication types and a Windows Live ID for Passport authentication.

Password

Text

Yes

(Empty)

PASSWORD="encryptedText"

The password of the account used to establish a Dynamics CRM server connection.

Domain name

Text

No

(Empty)

DOMAIN="networkautomation.com"

The name of the domain that will verify user credentials.

Organization name

Text

Yes

(Empty)

ORGANIZATION="Network Automation"

The name of the organization associated with the account. To query organization names and Dynamics CRM server URIs that exist on the system, click Discover.

Session

Text

Yes

DynamicsCrmSession1

SESSION="DynamicsCrmSession1"

The name of the session in which to  link subsequent Dynamics CRM activities. To end a session, use the Dynamics CRM - End session activity.

Auto discover

Yes/No

No

No

AUTODISCOVER="Yes"

Auto-discovery helps you detect where the Dynamics CRM components are installed, whether locally or remotely. If set to YES, will use CrmDiscoveryService to obtain a name and URL endpoint for a target organization (set to NO by default). The CrmDiscoveryService Web service is accessed through a global URL of an on-premise Microsoft Dynamics CRM server. Each Microsoft Dynamics CRM server hosts the CrmDiscoveryService Web service, which is located here: http://<server:port>/MSCRMServices/2007/AD/CrmDiscoveryService.asm.

NOTE: Setting this parameter to YES inactivates various settings.

Discovery URI

Text

No

No

DISCOVERYURI="crm.disco.com"

The Discovery URL used by your site if you are connecting to a Microsoft Dynamics CRM Online organization. To connect to Microsoft Dynamics CRM Online, the discovery service is first hit to retrieve a passport authentication ticket. This ticket indicates that a Live ID user is, in fact, authenticated to use the Microsoft Dynamics CRM Online instance.

Organization URI

Text

No

No

ORGANIZATIONURI="crm.org.com"

The URL of the organization service. If the Auto discover parameter is set to YES, this parameter becomes inactive.

Home realm URI

Text

No

No

HOMEREALMURI="crm.home.com"

The URL of the home realm. This is the address of the identity provider. If the Auto discover parameter is set to YES, this parameter becomes inactive.

Authentication type

Text (options)

No

No

  1. AUTHTYPE="ActiveDirectory"

  2. AUTHTYPE="Federation"

  3. AUTHTYPE="LiveId"

  4. AUTHTYPE="OnlineFederation"

The type of authentication used to connect to the Dynamics CRM server. If the Auto discover parameter is set to YES, this parameter becomes inactive. The available options are:

  • None - Authenticates with Dynamics CRM using the current Windows credentials of the application. This is typically used in development environments and only works with on-premises deployments in the same Active Directory domain (or trusted domain) as the Microsoft Dynamics CRM server.

  • Active Directory - Authenticates using Active Directory credentials of a specific service account. This is mainly used for on-premises deployments.

  • Federation - Establishes an authentication gateway using a combination of IAG and Active Directory Federation Services (ADFS) in order to provide external users with access to the sensitive information that is stored in the CRM system without having to create Active Directory trusts.

  • Live ID - Authenticates using the Windows Live ID authentication mechanism (previously known as Passport authentication). Mainly used for Microsoft Dynamics CRM Online deployments.

  • Online Federation - Contains the available identity providers for the Microsoft Dynamics CRM Online service.

Timeout (seconds)

Number

No

120

TIMEOUT="180"

The total amount of time (in seconds) to allow for a synchronous connection request to the CRM server to complete. If this value is surpassed, a timeout error will occur. The default value is 120 seconds (3 minutes).

Advanced Properties

Property

Type

Required

Default

Markup

Description

Microsoft Office 365

Yes/No

No

No

OFFICE365="YES"

If set to YES, connection will be established via Office365 account. Set this option to YES if using  Microsoft Dynamics CRM Online through Microsoft Outlook. Set to NO by default.

Auto discover

Yes/No

No

No

AUTODISCOVER="YES"

If set to YES, will use CrmDiscoveryService to obtain a name and URL endpoint for a target organization (set to NO by default). The CrmDiscoveryService Web service is accessed through a global URL of an on-premise Microsoft Dynamics CRM server. Each Microsoft Dynamics CRM server hosts the CrmDiscoveryService Web service, which is located here: http://<server:port>/MSCRMServices/2007/AD/CrmDiscoveryService.asm.

NOTE: Setting this parameter to YES inactivates various settings.

Discovery URI

Text

No

No

DISCOVERYURI="crm.disco.com"

The Discovery URL used by your site if you are connecting to a Microsoft Dynamics CRM Online organization. To connect to Microsoft Dynamics CRM Online, the discovery service is first hit to retrieve a passport authentication ticket. This ticket indicates that a Live ID user is, in fact, authenticated to use the Microsoft Dynamics CRM Online instance.

Organization URI

Text

No

No

ORGANIZATIONURI="crm.org.com"

The URL of the organization service. If the Auto discover parameter is set to YES, this parameter becomes inactive.

Home realm URI

Text

No

No

HOMEREALMURI="crm.home.com"

The URL of the home realm. This is the address of the identity provider. If the Auto discover parameter is set to YES, this parameter becomes inactive.

Authentication type

Text (options)

No

No

  1. AUTHTYPE="ActiveDirectory"

  2. AUTHTYPE="Federation"

  3. AUTHTYPE="LiveId"

  4. AUTHTYPE="OnlineFederation"

The type of authentication used to connect to the Dynamics CRM server. If the Auto discover parameter is set to YES, this parameter becomes inactive. The available options are:

  • None - Authenticates with Dynamics CRM using the current Windows credentials of the application. This is typically used in development environments and only works with on-premises deployments in the same Active Directory domain (or trusted domain) as the Microsoft Dynamics CRM server.

  • Active Directory - Authenticates using Active Directory credentials of a specific service account. This is mainly used for on-premises deployments.

  • Federation - Establishes an authentication gateway using a combination of IAG and Active Directory Federation Services (ADFS) in order to provide external users with access to the sensitive information that is stored in the CRM system without having to create Active Directory trusts.

  • Live ID - Authenticates using the Windows Live ID authentication mechanism (previously known as Passport authentication). Mainly used for Microsoft Dynamics CRM Online deployments.

  • Online Federation - Contains the available identity providers for the Microsoft Dynamics CRM Online service.

Timeout (seconds)

Number

No

120

TIMEOUT="180"

The total amount of time (in seconds) to allow for a synchronous connection request to the server to complete. If this value is surpassed, a time out error will occur.

Proxy type

Text (options)

No

No

  1. PROXYTYPE="none"

  2. PROXYTYPE="http"

The type of proxy in which to connect to. The available options are:

  • System default - Connect to the default proxy server currently recognized by the system.

  • None - No proxy connection required.

  • HTTP - Connect to an HTTP proxy.

Use authentication

 

 

 

 

If enabled, specifies that the proxy requires authentication before granting access to resources. If disabled (default), specifies that no authentication is required. This is a visual mode parameter only used during design time, therefore, it contains no properties or markup. This parameter is active only if the Proxy Type parameter is set to HTTP.

Proxy server

Text

Yes if proxy type is HTTP

No

SERVER="proxy.server.com"

The host name or IP address of the proxy server. This parameter is active only if the Proxy type parameter is set to HTTP.

Proxy port

Number

No

(Empty)

PROXYPORT="1028"

The port that should be used to connect to the proxy server. This parameter is active only if the Proxy type parameter is set to HTTP.

Proxy username

Text

No

(Empty)

PROXYUSER="username"

The username  used to authenticate connection with the proxy server (if required). This parameter is active only if the Proxy type parameter is set to HTTP.

Proxy password

Text

No

(Empty)

PROXYPWD="encrypted"

The password used to authenticate connection with the proxy server (if required). This parameter is active only if the Proxy type parameter is set to HTTP.

Description tab - A custom description can be provided on the Description tab to convey additional information or share special notes about a task step.

Error Causes tab - Specify how this step should behave upon the occurrence of an error. (Refer to Task Builder > Error Causes Tab for details.)

On Error tab - Specify what AWE should do if this step encounters an error as defined on the Error Causes tab. (Refer to Task Builder > On Error Tab for details.)

Example

The sample AML code below can be copied and pasted directly into the Steps panel of the Task Builder.

Description: Create entity example that begins a 'Create Session' activity and ends with an 'End Session' activity.

<AMDYNAMICSCRM ACTIVITY="create_entity" SESSION="DynamicsCrmSession1" 
ENTITY="account" RESULTVARIABLE="theVar"><ATTRIBUTE 
LOGICALNAME="the_name_sample" TYPE="String" 
 VALUE="the_value_sample" /></AMDYNAMICSCRM>


<AMDYNAMICSCRM ACTIVITY="create_session" 
PROTOCOL="http" SERVER="209.223.157.138" USERNAME="administrator" 
PASSWORD="AM4/Q7bbHbt9QhISwlRVy6FfQHONLtbjckKaME" DOMAIN="netautoinc" 
ORGANIZATION="netautodyn" DISCOVERYURI="http://209.223.157.106/
XRMServices/2011/Discovery.svc" ORGANIZATIONURI="http://dynamicscrm2011/
netautodyn/XRMServices/2011/Organization.svc" 
AUTHTYPE="ActiveDirectory" SESSION="DynamicsCrmSession1"/>

<AMDYNAMICSCRM ACTIVITY="end_session" 
SESSION="DynamicsCrmSession1" />