Using Web Services with External Messages

about using external messages docid 7lsl3wro0zatll81sdrsysecurity features when using external messages docid 7lsl3wro0zatll81sdrsythird party configuration example docid 7lsl3wro0zatll81sdrsycreating a script for ivanti to process external messages docid 7lsl3wro0zatll81sdrsyconfiguring the api key docid 7lsl3wro0zatll81sdrsyconfiguring the message handler docid 7lsl3wro0zatll81sdrsysetting the trusted ip addresses docid 7lsl3wro0zatll81sdrsy about using external messages this feature allows to accept external messages, such as web service calls, that are generated externally this allows different applications with different infrastructures to communicate with each other without either application having to change their internal structures and logic for example, an external vendor such as salesforce com may trigger an event in based on an action in their application when a user in salesforce com updates an account status, their application sends a message to to inform us of the account change does not have control over the format of the external message and so must be able to accept messages in any format, in order to process the data in the message uses the message queue and scripts to transform the data in the external message and to send a response to the external application security features when using external messages this features uses the following security measures you can set the ip addresses, or a range of ip addresses, from which to accept external messages you can also block ip addresses checks the ip address at both the application level and at the tenant level see setting the trusted ip addresses docid 7lsl3wro0zatll81sdrsy every external message must contain a valid api key in the url this api key must match the customer defined api key in the database if there is no valid api key, ignores the external message see configuring the api key docid 7lsl3wro0zatll81sdrsy you can optionally enable the script to limit the amount of data that it accepts in the external message third party configuration example the following configuration information is an example only it is described here for informational purposes only this configuration is not part of and is subject to change your third party integration may be completely different from the one described here it is only included to help you understand the external message format and process the following example is for salesforce com it shows how whenever an account number that starts with 3 is added or modified, salesforce com sends an external message to that updates the corresponding record in the application the user does the following logs into a third party application; in this case, salesforce com creates a new workflow rule using the account object the workflow rule is triggered whenever an account is created or edited, with the criteria of the account number starts with a 3 creates an action to send a message to every time that the workflow rule runs the message contains the account number change this message must contain the url and the url must contain the api key see configuring the api key docid 7lsl3wro0zatll81sdrsy activates the workflow when an account that starts with 3 is created or updated, salesforce com sends an external message to creating a script for ivanti to process external messages follow these steps to configure to process the external message from the configuration console, click extend > integration tools > web service connections (beta) to open the web service connection manager (beta) workspace under calls from external web services to system (incoming) , click new service enter information into the fields field description integration name a unique name for this integration description optional a description of the integration response xml (optional) optional contains the xml formatted response that sends to the third party integration upon receipt of the external message click next the application displays the script page in the service reference field, click add new\ the application displays the create service reference dialog box enter information into the fields field description integration name read only the name of the integration service reference a unique name for this service reference service address (url) the url where the third party integration sends the external message this url must be the same as the url used by the third party integration an example is https //integration saasit com/ company name /accountupdate asmx click save the script page does not show any request data until you receive a request from the third party integration go to third party integration and send an external message to this populates the script page with request data now you need to create the script that uses whenever it receives the external message from the third party integration this script tells the application how to process the external message browse the request data for the information to add to the script snippet section for example, if you configured the the third party integration to send an external message whenever the account information changed, you might add the variable information for the account variable (shown in the request data section) to the script snippet section click the variable name in the request data section to generate the variable information and add it to the script snippet section click append to move the script snippets to the scripts section relationship between data update the code in the scripts section until you have created your script click save whenever receives an external message, it executes the script on the external message to process it configuring the api key from the configuration console, click configure > security controls > api keys to open the api keys workspace click add key group to create a new api key group enter a name and optionally a description for the new api key group click save key group and then click back to return to the api keys workspace under key groups , highlight the new api key group that you created click add api key to generate an api key the application displays the new api key page with a reference id already populated click save key and then click back to return to the api keys workspace the application displays the new api key all external messages must contain this api key; otherwise will not process the message configuring the message handler you need to configure a message handler to handle the external message log into the configuration database (configdb) open the message queue handler workspace click new message queue handler enter information into the fields, noting the following the value in the endpoint field must be the url of the integration service for example, enter http // your ip address /integrationservice svc strongly recommends using the secure protocol https instead of http within the platform to ensure data security and integrity the value in the dispatch method field must be set to handlewebservicemessage the name must match exactly click save see the configuration database guide for for more information about using the configuration database setting the trusted ip addresses the application only processes external messages from ip addresses that are on the trusted ip address list before you proceed, ensure that you have the list of ip addresses for your third party integrations log into the application open the integration trusted host workspace click new integration trusted host enter information into the fields field description name a unique name for this trusted host description (optional) a description of this trusted host start ip the first ip address in a series of ip addresses to allow end ip the last ip address in a series of ip addresses to allow click save