Working with Shopping
Shopping Central installer properties
Shopping Receiver installer properties
Shopping Admin Console settings
1E Client Shopping module settings
Configuring AD synchronisation
Default and recommended Configuration Manager legacy package settings
Fields and limitations
The Shopping workflow
Shopping and other ticketing systems
Deploying Shopping Administrator Console using Configuration Manager
Windows Servicing Assistant UI Pages
- Supported Platforms
The Shopping workflow extends the default Shopping Progress Provider feature by allowing VBScripts to be executed asynchronously during workflow transitions so that Shopping can communicate progress about the application request to third-party applications.
Two types of workflow integration can be configured:
- Shopping request workflow for applications
- Shopping OS Deployment workflow
Configuring Shopping request workflow integration
Workflow Integration is managed from the Shopping Admin Console. To configure workflow integration:
- In the Shopping Admin Console, choose Settings node.
- Expand the Workflow Integration settings – there are 8 parameters for Workflow Integration:
- the first 6 parameters are for defining the location and names of the workflow scripts.
MaxWorkflowRetriesis the retry count for failed scripts (default value is 3) but can be modified on-demand.
WorkflowIntegrationModeis the nature of the integration. Choose from one of the following:
Value 1. New request 2. Approval update 3. Approval process complete 4. Application request deployed 5. Installation process completed 6. Application request cancelled
Other workflow configurations to consider are:
Workflow script location
The name and location for each VBscript file is defined in the Workflow Integration table under Shopping Admin Console settings.
Timeout for VBscripts files
The default timeout for VBscripts to execute is defined in the Central service table under Shopping Admin Console settings.
Location of temporary files
When a file needs to be executed, the Central service makes a temporary copy in this location folder, with its name is appended with the RequestRef. It is then parsed so that its variables are replaced with values, then executed and deleted.
Interval for pending requests
The default interval for polling requests is defined in the Central service table under Shopping Admin Console settings.
An overview of the Shopping request workflow is provided in the below diagram. This is for applications only, the OS deployment workflow is outlined further below.
The numbers in blue boxes are for ease of reference only. The numbered iems in red refer to the workflow integration points listed in the table above. The Mail items in purple text refer to emails sent at each stage, and are decribed further in Localizing Shopping.
Configuring the OS deployment workflow
We've introduced a new workflow feature from Shopping v4 – the OS deployment (OSD) workflow. It differs from the Shopping request workflow for applications in that it is self-service with no approval. Furthermore, it can be scheduled to be delivered at a future date and time (depending on the licensing model) and at a time convenient to the shopper.
Shoppers can request an OS deployment by using the OSD wizard on the Shopping home page. Progress is saved for that shopper until the wizard is complete.
When the request for an OS deployment is due, the system automatically submits an order for ConfigMgr to process. OSD workflow transitions have events associated with them and for each of event, there is an associated XML file describing the status of the transition.
The XML contains the following sections:
Shopping applications are set up in the Shopping Admin Console. You may also want to define a unique Application Ref for each Application you will be accessing in your custom interface. This information is not mandatory, but helps to identify Shopping applications using a unique ID that is meaningful to the calling application. For example this could be an identifier from a third-party purchasing, inventory or license management system.
Application Ref must be unique. It is best practice to use an appropriate format that reflects all the reasons for having a unique reference for each application. For example, is the application ConfigMgr or non-ConfigMgr, supported OS, global or regional.
Workflow integration files
These integration files are used to make calls to third-party APIs, update the database or write a text file with data from each stage of the Shopping workflow. There are currently 6 application templates (one for each stage of the workflow) as well as 5 OS deployment templates located in the
WorkflowIntegration folder for the Shopping Central Service:
|Integration file||Workflow type||Description|
|Application||Called when a new application is requested (including requests made by administrators on behalf of others)|
|Application||Called when approval and license checks are completed for an approval application for the following conditions:|
|Application||Called at the end of the approval process irrespective of whether or not approval is enabled for an application for the following conditions:|
|Application||Only applicable to SMS/SCCM applications and is called when a request to SMS/SCCM is deployed.|
|Application||Called when the SMS/SCCM installation process is completed.|
|Application||Called when an existing application request is cancelled.|
|OSD||Called when an OSD event is cancelled.|
|OSD||Called when there are changes to an OSD event which hasn't been submitted.|
|OSD||Called when an OSD event is completed.|
|OSD||Called when an OSD event is created.|
|OSD||Called when an OSD event is submitted.|
The installed versions of these files simply creates a text file with common data. You will need to customize them to make them useful. Take a look at the Workflow integration parameters to see the extent of the customization.
The parameter to make note of is
%FINALSTAGE%. It indicates if the executed script is the last one for the active workflow dependent on the integration mode.
Application script processing
Workflow stage details are written to the
tb_WorkflowIntegration_Requests which maintains a strict ordering of the workflow requests. It also holds status information for the associated integration scripts. The central service polls this table every 10 seconds for pending requests and performs the following actions:
- Reads the workflow integration request including workflow stage and request ref
- Loads the scrpit associated with that particular workflow stage
- Substitutes script parameters with data for the request details
- Executes the script
- Waits for the script to return with a status code or timeout
- Updates the state of workflow request in the table
Workflow status in this table may be one of the following:
- Pending – request is yet to be processed
- Retry – the script was executed and either returned an error or timed out (with the process successfully terminated) and has retries remaining. The retry takes place when the central service retry job executes.
- Failed – the script was executed and either returned an error with no retries remaining or timed out with the process still running.
- Suspended – scripts with an overflow step or sequence are being retried.
- Complete – request is processed successfully. If this is the last step for the application, all records with the same request reference are removed from the database.
OSD script processing
The Shopping central service runs the Event Processor listener that continuously polls for OSD events every 5 minutes. When it finds an event, it looks up the name of the event and locates a.vbs file of the same name as the event in
C:\Program Files (x86)\1E\Shopping\CentralService\WorkflowIntegration.
The Event Processor listener creates a temporary file on disk, injects the event XML into it and executes the .vbs file, passing in the path to the event data file.
The location of the temporary files is specified by the Shopping Admin Console Central Service setting Script Temp Path. By default this is
C:\ProgramData\1E\ShoppingCentral\temp. The Shopping Central service account must have admin rights to this location.
The temporary file has the same name as the template appended with the RequestRef GUID. If the execution fails (return code
1) a new row with the return code, the standard error and standard output of the script is created in the
EventProcessingResult table (to help Shopping administrators to troubleshoot non-delivered events).
The event is retried until the retry count is exhausted whereby the event is set to Failed. This event is ignored until its status is set to Pending by the Shopping administrator. The event is set to Complete when the script is successfully executed. If no corresponding .vbs file is found, the event is considered to be processed and its state is updated to Complete.
OSD databasbase schema
OSD event sources are stored in the
tb_DomainEventSource table where:
- Name is the name of the source. For OSD the name is
- Reference is a unique identifier that refers to the OSD order. The reference should be used by external systems to refer back to shopping orders. This column has same value as those in
OSD events are stored in
tb_DomainEvents table and contain an XML document that represents a snapshot of the particular OSD item where:
- Timestamp is the date and time a particular event happened and is used to determine the order in which the events are getting processed
- Name is the name of the event
- Sequence is the order in which events have happened for a particular event source
- DomainEventSourceId is the ID of the source of the event
- State refers to the event delivery status
- Data is an XML document with the state of the OSD and its associated values
The results of integration scripts execution are stored in
- DomainEventID is the ID of the event this record is linked to
- Timestamp the date and time the script was executed
- ReturnCode is the return code for the script
- ResultData in case of a script error, this is the captured standard output and standard error to help troubleshooting efforts
When the OSD workflow completes, the Event Processor deletes all the events and results associated with the order.
OSD integration XML files
Each workflow transition has an event associated with it and for each event there is a corresponding XML file that details the status for a particular transition. The XML files contain the following sections:
</RequestItem> – the OSD request item or application that is defined in Admin Console
</DeploymentItem>– the user preferences for the deployment, for example scheduling, application re-installs, etc.
</Order> – the order entity (
tb_CompletedOrder) created to track the progress of the deployment
</User> – the user who performed the action
</Machine>– the machine the OS deployment is for
Sample item created XML
Sample event changed XML
Sample event cancelled XML
Sample event submitted XML
Sample event completed XML
An application request example
What we're going to do is to show you how to customize
ApplicationRequested.vbs to create a ticket using the
This method takes
TicketID (the Request Ref) and
<Password> are the user credentials of the Shopping requester.
This is result of the
ApplicationRequestedt.vbs script when the workflow parses it:
Notice how the script uses the
WScript.Quit method to pass a return code for the status of the execution. All workflow integration scripts return
0 on success or
1 on error.
In this example, we are able to use the
TicketID in the create method. However, it the thrid-party application does not support this, we can replace the Shopping Request ref with a ticket ID returned from the third-party application (this ID must be unique in the Shopping database) by calling the ShoppingAPI2
UndateRequestRef method from
And if you wanted to use
ApplicationRequestedt.vbs to insert a record into a database table, here's how to do it. In this example, we're going to insert a record in the
NewRequests table in the TicketingSystem database.
Workflow integration parameters
The summary of theparameters for each of the Shopping workflow stages and their full description is detailed below.
VB Script parameters
|Parameter||Used in VB scripts||Description|
|The text specifying a link to a file share, for example where an application uses AD integration.|
|The display name of the application.|
|Whether the application is approved (|
|Whether the request deployed is for an install (|
|Whether the application was uninstalled (|
The type of the application request. One of:
|The type of the approval update. One of:|
|The type of the approval update. One of:|
|The comments of the Approver (blank if not applicable).|
|The email of the Approver (blank if not applicable).|
|The full name of the next Approver (blank if not applicable).|
|The full name of the Approver (blank if not applicable).|
|The comment associated with the application request (blank if not applicable).|
|Whether the deploy has been deferred to a later date.|
|The description of the application.|
|This parameter indicates if the current workflow stage being executed is the final stage script that will be executed for that particular request. Which script will be the final stage is affected mainly by the workflow integration mode and the application type.|
|The full name of the user who requested the application.|
|The ConfigMgr client GUID for the machine on which the request was made.|
|Whether there were Approvers associated with the request (|
|Whether the application has licensing (|
|Whether the install/uninstall was successful (|
|The current number of licenses used for the application.|
|The NETBIOS name of the machine on which the request was made.|
|The max license count for the application.|
|The email of the next Approver (blank if not applicable).|
|The full name of the next Approver (blank if not applicable).|
|Whether the application is non ConfigMgr.|
|The percentage of current licenses used for the application.|
|The date until the deployed has been deferred until (blank if not applicable).|
|The ConfigMgr site code associated with the machine on which the request was made.|
|The ConfigMgr Installation PackageID of the application (blank if not applicable).|
|The ConfigMgr Installation Package Name of the application (blank if not applicable).|
|The ConfigMgr Installation Program Name of the application (blank if not applicable).|
|The ConfigMgr Uninstall PackageID of the application (blank if not applicable).|
|The ConfigMgr Uninstall Package Name of the application (blank if not applicable).|
|The ConfigMgr Uninstall Program Name of the application (blank if not applicable).|
|The third-party reference for the application|
|The unique Request reference common to each stage of the workflow.|
|The current license threshold setting for the application.|
|The reason for the uninstall (blank if not applicable).|
|The account of the user who requested the application.|
|The email of the user who requested the application.|
|The workflow stage that the script corresponds to. One of:|
|The date at which the workflow integration request was added to the database in UTC.|