-->
Important
Working with Projects create project and add multiple WSDL to one project; Webservices Description Language, XML, WSDL, SOAP and REST protocols; 4 hours of XML TESTING VIDEOS; Web Services with SoapUI Pro; Adding properties to Project and how to use the values from project level and Test Suite level properties indifferent scenarios; Mock. Click on the main toolbar or right-click the root node in the Navigator panel and select Import Project: In the Select SoapUI Project File dialog, select the Sample-SOAP-Project-soapui-project.xml file from the /SoapUI-Tutorials folder. The sample project will be shown in the SoapUI Navigator.
Dynamics 365 for Finance and Operations is now being licensed as Dynamics 365 Finance and Dynamics 365 Supply Chain Management. For more information about these licensing changes, see Dynamics 365 Licensing Update.
At https://github.com/Microsoft/Dynamics-AX-Integration, Microsoft provides sample code for consuming services. However, there are many scenarios where the other endpoint in an integration might not use a Microsoft stack. Even when the other endpoint does use, for example, the Open Data Protocol (OData) client code that Microsoft makes available, you might find it useful to perform the following actions:
- Explore and analyze how an interaction's messages are constructed.
- Test the response of a service to a well-known request.
- Determine how exceptions will appear to the other endpoint.
Many frequently used tools that will help you perform these actions are available. This topic isn't an endorsement of any tool. Although it provides examples that use some frequently used software utilities, the principles should broadly apply to other, similar tools.
Prerequisites
Before you can test a service by using an external application, you must register the application in Microsoft Azure, and in Finance and Operations.
For details, see:
Query OData by using Postman
Postman (https://www.getpostman.com/postman) is a tool that is often used to interact with RESTful services (such as OData) in scenarios that involve the development and testing of application programming interfaces (APIs). This procedure isn't an endorsement of Postman, and other similar tools are available. However, we are using Postman to illustrate the concepts and messages that are involved when you use OAuth to authenticate with Azure AD, and then make OData requests to and receive responses from the application.
- Start Postman.
- In the upper-right corner, select the gear button, and then select Manage environments to create or update an environment.
- Enter a name for the environment, and then select Bulk Edit.
- Enter key-value pairs as shown in the following table. Enter one pair per line, and separate the key and value by using a colon (:).
Key Value tenant_id The Azure tenant ID that you looked up during the setup of prerequisites client_id The Azure AD application ID that you registered during the setup of prerequisites client_secret The secret key that you generated during application registration during the setup of prerequisites grant_type client_credentials resource The base URL of the instance without the trailing '/' - To verify that the key-value pairs can be parsed correctly, select Key-Value Edit, and review the results.
- Close the environment page.
- In the field to the left of the gear and eye buttons, select the new or updated environment.
- To retrieve an Azure AD token, create a POST request that has a URL in the format
https://login.microsoftonline.com/[tenant ID]/oauth2/token
.You can use a URL parameter that refers to the tenant_id environment variable, such ashttps://login.microsoftonline.com/:tenant_id/oauth2/token
. - On the Body tab, add body elements as request parameters that refer to the environment variables that you created earlier. Select Bulk Edit, enter the keys from the previous table, enter a colon (:), and then enter the key name again but enclose it in double braces ({{}}). Enter one request parameter per line. For example, enter grant_type:{{grant_type}}. Here is an example.
- On the Tests tab, create a test that validates that the response is reasonable, and that stores the returned authorization token in an environment variable. Here is an example.
- Select Save, enter a name and collection for the request, and then select Save again.
- Select Send to make the authorization request. The Body tab should now contain an Azure AD token together with other response details.
- Because of the test code, the token is now in an environment variable. You can see that the token is an environment variable by selecting the Environment quick look button (the eye button).
- Create a request to perform create, read, update, or delete (CRUD) operations on the desired data entity via the OData service. Create the URL according to your requirements. For more information, see Open Data Protocol (OData). You might find it useful to parameterize the request by using a variable that is stored in the environment, as shown earlier. The following example of a GET query uses a Customer Account parameter. The query returns name and address details for the customer account that is specified in the environment variable. Note that special characters must be correctly URL-encoded.
- Add an Authorization header that refers to the authorization token that was retrieved earlier and stored in the bearerToken environment variable. The token must be prefixed by Bearer in the header.
- Create a test to help validate the response. The following example tests that non-empty, JSON-formatted data is returned in the response body.
- Save and send the request, and then verify the result. You must ensure that the user account being used is set to a default company that has data. Alternatively, you can also specify cross-company=true as the query parameter in the OData request.
In our example, we have now successfully authenticated and then used the OData service to read a customer record.
Query the SOAP custom service in your application by using SoapUI
SoapUI (https://www.soapui.org/) is a tool that is often used to interact with SOAP and REST web services in scenarios that involve API development and testing. This procedure isn't an endorsement of SoapUI, and other similar tools are available. However, we are using SoapUI to illustrate the concepts and messages that are involved when you use OAuth to authenticate with Azure AD, and then make SOAP requests to and receive responses.
- Start SoapUI, and select the SOAP button to create a project.
- Complete the information for the project:
- In the Project Name field, enter a name for the project.
- In the Initial WSDL field, enter the service address, and add the suffix ?wsdl. (The service address should be in the format [Finance and Operations instance base URL]/soap/services/[service group name].) For more information, see the Services home page.For example, we are querying the user session service at the URL
https://[Finance and Operations base URL]/soap/services/UserSessionService?wsdl
. - Select the Create sample requests for all operations? check box.Because you selected to create sample requests, one sample request is created for each service operation that is available.
- Right-click the new project, and then select New TestSuite to create a test suite. This test suite will generate a POST request for an Azure AD authorization token.
- Right-click the test suite, and then select New TestCase.
- Expand the test case, right-click Test Steps, select Add Step, and then select HTTP Request.
- Enter a name for the request, and then select OK.
- Enter a name for the test step. The endpoint that you should use for the POST request is
[https://login.microsoftonline.com/[tenant_id]/oauth2/token](https://login.microsoftonline.com/%5btenant_id%5d/oauth2/token)
. - Use the plus sign (+) button next to Parameters to add the following values.
Parameter Value grant_type client_credentials client_id The application ID from the Azure AD application registration client_secret The secret key value from the Azure AD application registration resource The URL of the instance without the trailing '/' - To make sure that the parameters are in the POST body, select Post QueryString, and then select Play. An access token should be returned in the response pane. The values will be most readable if you use the JSON response tab. Copy the access token so that you can use it in the authorization header of subsequent requests.
- Go back to the first request node under the GetUserSessionInfo SOAP sample request. In the request pane on the left, select the plus sign (+) button to add a header that is named Authorization. Paste the access token into the Value field, and add the prefix Bearer.
- The sample requests that SoapUI creates won't work unless you modify them. You must edit the call context and body so that they are consistent with the schema for what you're trying to do.For our simple scenario, you can edit the optional call context elements so that they are null-valued. Insert a forward slash (/) before the greater than sign (>) in the opening tags. Then comment out the question marks (?) and the closing tags by using the standard <!--...--> syntax to delimit the start and end of the comments. (Question marks aren't valid content for the XML schema.) Alternatively, you can just delete the question marks (?) so that the context elements are empty.
- The SOAP request is now ready. Select Play, and validate the result on the right.
In our example, we have now successfully authenticated and then queried UserSessionService via SOAP.
-->This article describes how to create a new project for your data source in the Web Service Configuration Tool. Follow these steps to create a project.
- Open the Web Service Configuration Tool. It opens a blank project.
- Select SOAP Project and then select Add.
- On the next page, provide the following information and then, select Next:
- The new web service name
- Address (WSDL path) to retrieve the exposed services, endpoints, and operations
- Namespace
- Security mode (authentication type)
- In this sample, the Credentials page is shown with the requirements for Basic security mode (the mode that was selected in the previous step). If 'None' was specified for the security mode, then a Credentials page wouldn't be displayed. Select Next.
- The WSDL path is being accessed to retrieve the service information and the list of exposed functions is displayed. If the WSDL path entered is incorrect, then the configuration tool fails to retrieve the service information and throws an error.
- Once the discovery is performed, then it lists the endpoint and the operations that are discovered. Select Finish.
- Compilation is performed. Compilation is a process of compiling the data contract assembly, which can be a time consuming operation. The user is informed about any compilation errors. After the discovery is performed, the tool displays the following page:
- Expanding SOAP project and selecting exposed endpoint provided below screen. This screen lists the operations that are declared under the endpoint.
- Expanding endpoint displays list of operations. An operation is a function declared by an Endpoint. Each operation addresses a type of task that can be performed within the service. This screen lists the arguments that are declared for the operation. These arguments are then defined when the operation is used in configuring the workflows.
- Next step is to define the connector space schema, which is achieved by creating the Object Type and defining their object types. Select Object Types and then select Add. In the new window, add a new object type and provide a name. Select OK.
- Adding an object type provides below screen.
- The right pane corresponding to object type allows you to maintain the attributes and their properties for the selected object type. Select Add. A new window is opened to add attributes:
- The following screen appears after adding all of the required attributes:
- Object type and attributes once created, provides blank workflows that cater to the operations performed in Microsoft Identity Manager 2016 (MIM).
Configure workflows in the Web Service Configuration Tool
The next step is to configure the workflows for your object type. Workflow files are a series of activities that are used by the Web Services Connector at run time. The workflows are used to implement the appropriate MIM operation. The Web Service configuration Tool helps you to create four different workflows:
- Import: Import data from a data source for the following two types of workflows:
- Full import: A full import that can be configured.
- Delta import: Not supported by the Web Service Configuration Tool.
- Export: Export data from MIM to a connected data source. The following three actions are supported for the operation. You can configure these actions based on your requirements.
- Add
- Delete
- Replace
- Password: Perform password management for the user (object type). Two actions are available for this operation:
- Set password
- Change password
- Test Connection: Configure a workflow to check if the connection with data source server is successfully established.
Note
You can configure these workflows for your project or download the default project from the Microsoft Download Center.
Workflow Designer
The Workflow Designer opens the work area to configure the workflow as per requirement. For every object type (new /existing), the configuration tool provides the nodes for workflows that are supported by the tool.
The Workflow Designer is composed of the following UI elements:
- Nodes in left pane: These help you to select which you want to design which workflow.
- Central Workflow Designer: Here you can drop the activities for configuring the workflows. To accomplish various MIM operations (Export, Import, Password management), you can use the standard and custom workflow activities of .NET Workflow Framework 4. The Web Service Configuration tool uses standard and custom workflow activities. For more information on standard activities, see Using activity designers.
- In the Central Workflow Designer, a red circle with exclamation mark beside any activity indicates that the operation dropped and is not defined correctly and completely. Hover over the red circle to find out the exact error. After the activity is defined correctly, the red circle changes to the yellow information mark.
- In the Central Workflow Designer, a yellow triangle information mark beside any activity indicates that the activity is defined, but there is more that you can do to complete the activity. Hover over the yellow triangle to see more information.
- Toolbox: Packages all the tools including system and custom activities and predefined statements to design the workflow. For more information, see Toolbox.
- Toolbox sections: The Toolbox has the following sections and categories:
- Description: The header of the Toolbox. One tab accesses the Toolbox and the properties of the selected workflow activity.
- Import workflow: Custom activities to configure import workflows.
- Export workflow: Custom activities to configure export workflows.
- Common: Custom activities to configure any workflow.
- Debug: System workflow activities for debugging defined in Workflow 4. These activities allow issue tracking for a workflow.
- Statements: System workflow activities defined in Workflow 4. For more information, see Using activity designers.
- Properties: The properties tab displays the properties of a particular workflow activity that is dropped in the designer area and selected. The figure on the left shows the properties of Assign activity. For every activity, the properties differ and are used while configuring the custom workflow. This tab allows you to define the attributes of the selected tool that has been dropped into the central workflow designer. For more information, see Properties.
- Task Bar: The task bar includes three elements: Variables, Arguments, and Imports. These elements are used together with workflow activities. For more information, see A developer's introduction to Windows Workflow Foundation (WF) in .NET 4.
Configure a full import workflow in the Web Service Configuration Tool
The following steps show how to configure full import workflows for SOAP by using the Web Service Configuration Tool.Warning
This sample only creates a workflow. Modifications to the workflow, such as to use custom logic in the API, may be required.
- Select the Full Import workflow to configure. The Arguments and Imports are already defined and are specific to the activities. See the following screens for more information.After the reconfiguration of the calls, change the names of the attributes that change, add or change the namespace to variables that refer to the return structure of the API and object types that refers to the old namespace. The toolbox in right pane holds all the custom workflow-specific activities that you require for configuration. Assign the values to the variables that you are going to use for your logic. Go to the bottom section of central workflow designer and declare the variables. Variables are declared in the next step.
- Add a Sequence activity. Drag the Sequence activity designer from the Toolbox and drop it on to the Windows Workflow Designer surface. Refer to the following screens. The Sequence activity contains an ordered collection of child activities that it executes in order.
- To add a variable, locate Create Variable. Type wsResponse for the Name, select the Variable type drop-down, and then select Browse for Types. A dialog is displayed. Select generated > default > Response. Keep the Scope and Default values unselected. Alternatively, set these values by using the Properties view.
- Now add all other variables and below is the final screen.
- Drag one more Sequence activity designer from the Toolbox within already added Sequence activity.
- Drag a WebServiceCallActivity presented under Common. This activity is used to invoke Web service operation available after Discovery. This is a custom activity and is common in different operation scenarios.To use the Web service operation, set following properties:
- Service Name: Enter a name for the web service.
- Endpoint Name: Specify an endpoint name for the selected service.
- Operation Name: Specify the respective operation for the service.
- Argument: Select Arguments. In the next dialog, assign the argument values, as shown in the following figure:ImportantDo not change the Name, Direction, or Type for an argument by using this dialog. If any of these values are changed, the activity becomes invalid. Only set the Value for the argument. As shown in this figure, the value wsResponse is set.
- Add a ForEach activity just below WebServiceCallActivity. This activity is used to iterate over all attributes (both anchors and non-anchors) of object type. While dragging this activity into your Workflow Designer surface, it automatically enumerates all attribute names for your object. Set required values as per the following screen:
- Drag a CreateCSEntryChangeScope activity within ForEach body. This activity is used to create an instance of CSEntryChange object in workflow domain for each respective record while retrieving data from target data source. Dragging this activity provides below screen. CreateAnchorAttribute activities are automatically inherited.
- Set the value of the DN expression as
‘string.Concat ('Employee',item.EmployeeID)’
. Set the AnchorValue for the EmployeeID to ‘Convert.tostring(item.EmployeeID)’. Set the ObjectTypeName as Employee. After making these modifications, you'll see the following screen:NoteAnchor values and object names vary according to the exposed web service. The figure shows an example. - Drag a CreateAttributeChange activity below the CreateAnchorAttribute activity. The number of activities to drag is equal to the number of non-anchor attributes. See the following figure for reference.
- Drag CreateValueChangeActivity within CreateAttributeChange activity and set attribute value as per below screen.NoteTo use this activity, pick and assign the respective fields from the drop-down and assign the values. For multivalued attributes, drop multiple CreateValueChangeActivity activities inside a CreateAttributeChangeActivity activity.
- To add conditions for an attribute, add an If activity as shown in the following figure:
- Finally, add an Assign activity and set the expression, as shown in the following figure:
- Save this project at the location
%FIM_INSTALL_FOLDER%Synchronization ServiceExtensions
.Default projects should be downloaded and saved at the location%FIM_INSTALL_DIR2010Synchronization ServiceExtensions
on the target system. The projects are then visible in the web service connector wizard.When running the executable file, you're prompted to specify the location for the installation. Enter the save location.ImportantThe project file can be saved and opened from any location (with the appropriate access privileges of its executor). Only project files that are saved to theSynchronization ServiceExtension
folder can be selected in the Web Service connector wizard that's accessed through the MIM Synchronization UI.The user who's running the Web Service Configuration tool requires the following privileges:- Full Control to the Synchronization Service Extension folder.
- Read access to the registry key
HKLMSystemCurrentControlSetServicesFIMSynchronizationServiceParameters
through which, the Extension folder path is located.
Configure export workflows in the Web Service Configuration Tool
The following sections show how to export your workflows by using the Web Service Configuration Tool.
Add workflows
Add export workflows by following these steps in the Web Service Configuration Tool.- Select the export workflow to configure. Under Export, select Add. The Arguments and Imports are already defined and are specific to the activities. See the following screens for reference.
- Add a Sequence activity. Drag the Sequence activity designer from the Toolbox and drop it on to the Windows Workflow Designer surface. The Sequence activity contains an ordered collection of child activities that it executes in order. Select Create Variable. Assign the values to the variables that you're going to use for your logic.NoteThe steps to add a variable are described in the section for creating full import workflows.
- Drag a ForEach activity within already added Sequence activity to iterate over anchor attribute values.
- Select Properties and set the Values as per below screen. Here objectToExport is argument.
- Set DisplayName as ForEach<AnchorAttribute>
- Set TypeArgument as
Microsoft.MetadirectoryServices.AnchorAttribute
. - Add a Switch activity within the ForEach body of the AnchorAttribute.
- Add an expression as per below screen.
- Select Add a new case and enter a value for the EmployeeId. Drag a Sequence activity and within it add an Assign activity.
- Assign the To and Value properties for the Assign activity.
- The ForEach activity is used for anchor values. Add another ForEach activity to assign non-anchor values. In this example, the AttributeChange anchor is used.
- Add a Switch activity within ForEach body of the AttributeChange anchor.
- Add an expression as per below screen.
- Select Add a new case and enter a value for the FirstName. Drag a Sequence activity and within it add an Assign activity. Assign the To and Value properties for the Assign activity.
- Add values for the required attributes like LastName, Email, and so on.
- Under Common, drag a WebServiceCallActivity and set Values for its Arguments.ImportantDo not change the Name, Direction, or Type for an argument by using this dialog. If any of these values are changed, the activity becomes invalid. Only set the Value for the argument. As shown in this figure, the value wsResponse is set.
- Finally, add an If activity to check responses that are returned from the web service operation.
Creation of the export workflow with the Add operation is complete:
Save this project at the location
%FIM_INSTALL_FOLDER%Synchronization ServiceExtensions
.Delete workflows
Delete export workflows by following these steps in the Web Service Configuration Tool.
- Select the export workflow to configure. Under Export, select Delete. The Arguments and Imports are already defined and are specific to the activities. See the following screens for reference.
- Add a Sequence activity. Select Create Variable. Assign the values to the variables that you are going to use for your logic.NoteThe steps to add a variable are described in the section for creating full import workflows.
- Drag a ForEach activity within already added Sequence activity to iterate over anchor attribute values.
- Select Properties and set the Values per below screen. Here objectToExport is argument.
- Set the DisplayName as
ForEach<AnchorAttribute>
: - Set the TypeArgument as
Microsoft.MetadirectoryServices.AnchorAttribute
: - Add a Switch activity within the ForEach body of the AnchorAttribute.
- Add an expression as per below screen.
- Select Add a new case and enter a value for the EmployeeId. Drag a Sequence activity and within it add an Assign activity.
- Assign the To and Value properties for the Assign activity.
- Under Common, drag a WebServiceCallActivity and set Values for its Arguments.ImportantDo not change the Name, Direction, or Type for an argument by using this dialog. If any of these values are changed, the activity becomes invalid. Only set the Value for the argument. As shown in this figure, the value employeeID is set.
- Finally add an If activity to check the responses returned from the web service operation.
Deletion of the export workflow with the Delete operation is complete:
Save this project at the location
%FIM_INSTALL_FOLDER%Synchronization ServiceExtensions
.Replace workflows
Replace export workflows by following these steps in the Web Service Configuration Tool.
- Select the export workflow to configure. Under Export, select Replace. The Arguments and Imports are already defined and are specific to the activities. See below screen for reference.
- Add a Sequence activity.
- Drag a ForEach activity for the <AnchorAttribute>.
- Add another ForEach<AttributeChange> activity to assign non-anchor values.
- Finally, the screen looks like the following figure. The instructions for configuring this activity are provided in the section for adding export workflows.
- Under Common, drag a WebServiceCallActivity and set Values for its Arguments.ImportantDo not change the Name, Direction, or Type for an argument by using this dialog. If any of these values are changed, the activity becomes invalid. Only set the Value for the argument. As shown in this figure, the value employee is set.
- Finally, add an If activity to check the responses that are returned from the web service operation.
Replacement of the export workflow with the Replace operation is complete:
Save this project at the location
%FIM_INSTALL_FOLDER%Synchronization ServiceExtensions
.Debug activities
The following custom activities are available to help debug the workflow template.
Log activity
The Log activity is used to write text messages to the log file. For more information, see Logging.
Note
If you aren't able to easily debug your workflow, try debugging the workflow in the production environment.
To use the Log activity, set the following properties. The properties are visible when you select the activity in Workflow Designer and view the Properties for the activity.
WriteLine activity
The WriteLine activity is used to write text messages to a provider's writer. If no writer is available, the WriteLine activity writes the text to the console window.
In the text box, write the message that you want to be visible in the writer target.
Important
The console window can't be used for this activity. Use another window output writer for this task.
To use the WriteLine activity, set the following properties. The properties are visible when you select the activity in Workflow Designer and view the Properties for the activity.
- Log Level: Specifies the amount of content to write in the log value. The possible values are:
- High: Write the LogText message to the log file if the log severity is set to High.
- Verbose: Write the LogText message to the log file if the log severity is set to Verbose.
- Disabled: Don’t write in the log file.
- LogText: Specifies the text content to write in the log.
- Tag: Adds a tag to the text to identify the type of content that's being written in the log. The possible values are: Error, Trace, or Warning.