Workflow Dialogs

Through Dialog Setup pages, system administrators can configure workflow dialogs per Brand, object type and action. When a client is about to show a workflow dialog, such definitions are requested through the GetDialog workflow service (as specified in the SCEnterprise.wsdl). Whenever the user selects another Brand, Issue, Category or status, the client requests for that dialog definition (requesting for GetDialog again) and redraws the entire dialog.

For Brand and overrule Issue selections, the redraw is needed because the entire workflow definition and dialog configuration could be different. For (normal) Issue selections the list of requested Dossiers could differ. For status- and Category changes, the Route To selection could differ. And, in all cases, the editable/read-only status could differ due to access rights.

System integrators can overrule the standard server behavior of the GetDialog service through server plug-ins. This is why clients should have no logics nor assume or predict certain behavior. Instead, they should listen to the GetDialog response and fully rely on that. The LogOn response should no longer be used by any 7.x compliant client to get definitions in relation to workflow dialogs. Also, there is no reason anymore to call the GetStates service since that is embraced by the GetDialog service.

History

• Since 5.0, the GetDialog service was introduced and used by the Web Editor only.

• Since 6.0, Publication Channel awareness has been added to the GetDialog service. Content Station started using it (but is still using the LogOn response too to build dialogs).

• Since 7.0, new features have been added to the service and InDesign / InCopy clients started using the service. The service itself is also improved and logics are moved from the clients to the service:

  • The returned PublicationInfo element tree has been pruned, clarifying what response information should be used by the clients.

  • The enabled status of properties is determined by the service (instead of the clients).

  • The Route To pre-selection is determined by the service (instead of the clients).

GetDialog service

[1] ‘Dossier’ is a property introduced in 7.0 and can be configured in the Dialog Setup Maintenance page. When a dialog is not customized, a default dialog is assumed by the server, which now also includes the Dossier property. Unlike other properties, the Dossier property is only shown in the dialogs when useful. That is, when the client and server can both handle it. If one doesn’t, the Dossier property won’t be shown in the dialog.

For client side, that means it is able to:

• Parse the Dossiers element in the GetDialog response.
• Draw a pull-down widget populated with those Dossiers.
• Pass the chosen Dossier ID (by the end user) through the object relations of the next request. For the Create dialog, that is the CreateObjects request.

For server-side, that means it is able to:

• Support the Object-in-Dossier relation. For example, for 7.0, Dossier-in-Dossier is not supported, and so Dossier and DossierTemplate objects won’t get a Dossier property.
• Support implicit Dossier creation for ‘next’ called service. Since 7.0. this is implemented for the CreateObjects service, and so, only for Create dialogs, the Dossier property is shown.

When a client does meet all its criteria listed above, it passes 0 (zero) or a valid Dossier ID for the DefaultDossier parameter; else nil. When the server received a 0 (zero) or valid Dossier ID, and all its criteria listed above are met, (and the Dossier is configured in the Dialog Setup, or default dialog is picked), it returns the Dossier property (through the GetDialogResponse->Dialog elements).

Clients do not worry about server criteria, so they pass 0 (zero) or a valid Dossier ID for any object type, including Dossier objects. Let’s assume that Enterprise Server 8.0 supports Dossier-in-Dossier relations. When a 7.x compliant client is talking to a 8.0 server, the Dossier property will then be shown in the dialog, and will work well.

Let’s assume that for Enterprise Server 8.0 the CopyTo dialog supports the Dossier property. Any 8.0 compliant client passes a value for DefaultDossier parameter and the server returns the Dossier property, which is shown in the dialog. The client then passes the chosen Dossier ID (by end user) through the CopyObjects service. But, when a 7.x compliant client is talking to a 8.0 server, the DefaultDossier parameter is set to nil, and no Dossier property is shown. And vice versa, when a 8.0 compliant client is talking to a 7.x server, the client passes a value for DefaultDossier parameter, but the server does not return the Dossier property, and so it is not shown in the dialog.

When the user is about to Create a new object, the server resolves and returns the Dossiers to let the user pick one. Even when there are no Dossiers found, the Dossier property is returned. Note that the “New Dossier” item (ID=-1) always exists in the list of Dossiers. This allows users to create a new Dossier, even when there are none found. There is also an empty item (ID=0) which means there is no need to create a Dossier. When a user submits the dialog, the client should pass the Dossier in the object relations (type Contained) of the CreateObjects request. (This should be done for ID <> 0 only.)

The Publication, Issue, Section and State parameters indicate the user’s selection in the workflow dialog. By passing those parameters, clients ask the server how the dialog should be drawn for the given publication/Issue, regardless of the actual publication/issue of the object as stored in the database. So, these parameters are ‘strongest’ and overrule any other sever logics deriving publication/Issue from parent objects, template objects, configured current Issue, etc, etc. Important is that clients pass -no- Publication parameter the ‘first time’. That way, server logics can kick in, but more over, custom server plug-ins can even overrule those logics by choosing specific publication/Issue. The ones that are initially picked by the server can be read from the GetDialogResponse -> Dialog -> MetaData.

The Publication, Section and State parameters imply what access profile is respected. For example, the “Change Pub/Issue/Category” option is resolved and so the properties mentioned are made read-only or editable (by GetDialog service).

The table below shows what combination of parameters are expected. Other combinations are not supported. As you can see, when asked for a Create action, no object ID should be passed, but a Type is required. For other actions, it is the other way around. And, only for redraw operations, Publication, Issue and Section should be passed. Except for creating new objects without Parent/Template; the client should pass a Publication, which should be taken from the context the user is working in. For example: the last used publication, or the publication currently selected in the Search pane.

Legend:

✔ = valid ID (not empty, not zero)

✘ = nil

- = depends on the action (inherited from one of the first three lines above)

1) For Save As operations, the Action parameter should be set to Create. Note: Although the dialog caption says Check-In, technically we speak of a Create action. 2) Whether or not a Parent (ID) or Template (ID) was provided. This is used to derive the publication (and overrule Issue) from. 3) When user selects other Brand or overrule Issue, a GetDialog request is fired and the dialog is redrawn. The entire dialog definition can change, so a full redraw is required. 4) For overrule Issue: ✔, but for normal Issue: ✘. 5) When a user selects (normal) Issue, section or status, GetDialog request is fired to let the server reflect access rights profile settings to the dialog fields, and to refill certain lists, such as Dossiers, sections and statuses.

GetDialogResponse

Exceptional standard dialog behavior

Disabling the Editions property

For Task, Hyperlink, Library, Plan and Other objects, Editions are always disabled.

Disabling Brand / Issue / Editions property for Layout Module placements

For objects placed on Layout Modules (or Layout Module Templates), the Brand, Issue and Editions properties are disabled. This is because Editions are inherited from the module and are not allowed to change (in order for its placements to preserve data integrity).

Disabling Brand / Issue / Editions / Category property for placements

The Create dialogs for Articles and Image objects show disabled Brand, Issue, Editions and Category properties when they are created from a Layout.

Disabling Status property and the Personal Status

For existing objects, the Change Status access option is respected, and so you will risk having a disabled Status property. This is correct, except when the Personal status is currently selected. (Reason: no-one else can see the object other than the user to whom the object is routed to, but that user cannot change the status, and so an admin user would need to be asked to solve this problem, which is unwanted.) So, when an object is in the Personal Status, the Status property is enabled.

Disabling properties in the Set Properties dialog

When an object is already locked for editing, the Set Properties dialog shows all disabled properties. This is done by the client, not by the server (because InDesign/InCopy clients do pessimistic locking and so in both cases the object is locked and the server cannot tell the difference). This implies that the Server Plug-ins cannot alter the enabled status of the properties in this specific situation.

Automatic user input focus

For workflow dialogs, the focus (caret) is set to the Status property. For the Create and Copy To dialogs, or when the Status property is disabled, the focus is set to the Name field.

Limited Edition items

When an object is placed on a Layout (or LayoutModule or Layout Template), the Create and Check-In workflow dialogs list limited Editions items: only those Editions that are currently assigned to the Layout.

Inactive, but assigned Issues

Inactive Issues are not listed in the workflow dialogs, except for those Issues (and their Editions) that are currently assigned to the object. The user can deselect such inactive Issues (because they are assigned). However, the next time the workflow dialog raises, unassigned Issues that are inactive are no longer listed.

‘Change’ access rights not applied to Create and Copy To dialogs

The Access Profiles Maintenance page contains the following ‘Change’ access rights options:

• Change Brand/Issue/Category
• Change Edition
• Change Status

By toggling the Brand/Category/Status properties in the Create dialog, because of the access rights mentioned, those properties could ‘suddenly’ get disabled. There would be no escape from that point. To avoid such deadlocks, the Brand/Issue/Category/Edition/Status properties are enabled for the Create dialog (except in case there are other rules telling to disable the properties, such as Create Article on a Layout Module for which they should be disabled). In short, the Create dialog ignores the ‘Change’ access options.

Property inheritance for Create and Copy To dialogs

When objects are about to be copied, or created from a template or directly created onto a parent layout, properties are inherited (from the source/template/parent object) and pre-filled in the dialog. This is done for all properties, except for the following:

• ID
• Document ID
• Name, Type
• Content Source
• Deadline
• Urgency
• Creator
• Created
• Modifier
• Modified
• Comment
• Status
• Route To
• Locked By
• Version
• Deadline Soft
• Rating

Those properties are cleared, and so empty properties are shown in the dialog. Nevertheless, some of those properties are automatically re-determined, such as: Name, Type, Status, Route To and Version. Those are pre-filled (with possibly a different value than the source object).

GetDialog2 service [since 8.0]

Smart Connection 7.x for InDesign / InCopy and Content Station 7.x call the GetDialog service each time when user changes a property value (dialog field) for which the ‘Refresh’ flag is enabled. The request contains the new user typed value. That way, a custom server plug-in is able to act on the change.

Since Enterprise Server 8.0, there is a new service, called GetDialog2, which supersedes the GetDialog service. Its request and the response are simplified to make it easier for clients, especially when it comes to refreshing dialogs. Basically it does the same, but instead of separate parameters, structured data trees are round-tripped through MetaData and Targets. This takes away the need to cache user typed data, which is quite complicated to merge on the way back. This makes clients rely even more on the server behavior, which results into more consistent behavior between clients.

At least for the 8.x versions, the GetDialog is still supported to allow clients to migrate to GetDialog2. Clients are encouraged to do so.

This is where clients pick-up data from server to show at dialog:

GetDialog2Response
	Dialog
		...
		MetaData
			MetaDataValue
	...
	Targets
		Target

When redrawing the dialog, the user typed data is round-tripped through the new parameters as follows:

GetDialog2
	...
	MetaData
		MetaDataValue
	Targets
		Target

For client convenience, the MetaData tree is not used (with BasicMetaData, etc), but instead, the list structure is used (with MetaDataValue). Custom properties are supported and are prefixed with “C_”.

In 7.x, the following properties are round-tripped through a fixed set of GetDialog service parameters:

GetDialog
	...
	ID
	Publication
	Issue
	Category
	Status
	Type
	...

There is one exceptional field; The RouteTo field should respect the Brand’s Routing configuration which is taken care of by the core server. The round-trips caused by the Refresh fields should not disturb this existing feature.

To optimize data traffic and server-side execution speed, clients can request for less data, in case they don’t need that much. In 7.x, this is done as follows:

<GetDialog>
	...
	<RequestDialog>true</RequestDialog>
	<RequestPublication>true</RequestPublication>
	<RequestMetaData>true</RequestMetaData>
	<RequestStates>true</RequestStates>
	<RequestTargets>true</RequestTargets>
	...

and as a result, the following data structure is filled in (or not):

GetDialogResponse
	Dialog
	Publications
	PublicationInfo
	MetaData
	GetStatesResponse
	Targets
	RelatedTargets
	Dossiers

Since 8.0, the response structure has changed into this:

GetDialog2Response
	MetaData
	Targets
	RelatedTargets

As you can see, there are much less data elements returned, since that data is now moved to the MetaDataValue structure with id-name pairs. And so, there is no longer need to have filtering parameters, which are therefore not present at the GetDialog2 request.

Show display names for internal values [since 8.0]

For configured data structures, such as Brands, Issues, etc, the client and server communicate DB ids, while showing display names to end users. To do such, both sides need to know about the configured data structures, which is very dedicated and therefore limited to built-in (known) properties. In 7.x, there is no common structure that can hold both internal values and display names. With Enterprise Server 8.0 there is, and so custom properties can use those, but also the built-in properties can be expressed in a more common way. This takes out some client logic, which makes things less dependent and specific.

The structure that holds the values, is defined as follows, whereby 8.0 changes are in bold:

<complexType name="MetaDataValue">
	<all>
		<element name="Property" type="xsd:string"/>
		<element name="Values" type="tns:ArrayOfString"
			minOccurs="0" maxOccurs="1"/>
		<element name="PropertyValues"
			type="tns:ArrayOfPropertyValue”
			minOccurs="0" maxOccurs="1"/>
	</all>
</complexType>

The following definitions are added since Enterprise Server 8.0 as well:

<complexType name="PropertyValue">
	<all>
		<element name="Value" type="xsd:string"/>
		<element name="Display" type="xsd:string" 
			minOccurs="0" maxOccurs="1"/> <!-- optional -->
	</all>
</complexType>
<complexType name="ArrayOfPropertyValue">
	<complexContent>
		<restriction base="soap-enc:Array">
			<attribute ref="soap-enc:arrayType"
			wsdl:arrayType="tns:PropertyValue[]"/>
		</restriction>
	</complexContent>
</complexType>

7.x example of usage, which is dis-encouraged:

<MetaDataValue>
	<Property>Publication</Property>
	<Values>
		<String>1</String>
	</Values>
</MetaDataValue>

8.0 example of usage:

<MetaDataValue>
	<Property>Publication</Property>
	<PropertyValues>
		<PropertyValue>
			<Value>1</Value>
			<Display>WW News</Display>
		</PropertyValue>
	</PropertyValues>
</MetaDataValue>

Sending values and display names (like above) are applied to Publications, PubChannels, Issues, Categories, Editions, Users and UserGroups.

Refresh dialog fields [since 8.0]

Workflow dialogs guide users through their workflow. Even though dialogs are already made very flexible, Enterprise Server 8.0 takes another step; It enables application engineers to redraw the dialog in specific cases for which some fields needs to be ‘refreshed’.

For example, a customer might wish that, when an end-user tags a checkbox ‘Department’ on a workflow dialog, the listed items at the Route To field gets filtered automatically, showing only the users and groups working for the same department as the current user.

Or the other way around, when the Route To field is changed by the end user, the customer might want to have a readonly ‘Department’ text field to be filled in automatically, with the value configured for the selected user.

There could also be a need to let one field depend on two others, and those fields do not necessarily have to be custom. For example, when the Issue field is set to a print channel and the Edition is set to ‘north’ only, the customer might wish to enter a simplified workflow and so less statuses needs to be shown at the Status field.

The triggers can be both ways, or relate one-to-many and/or custom fields or built-in fields can be involved. The rules and dependencies can be developed through a custom server plug-in. Admin users can not interfere with such complicated rules other than enabling or disabling the whole feature through the Server Plug-ins admin page.

A new flag added to the workflow WSDL, named ‘Refresh’:

<complexType name="PropertyUsage">
	<all>
		<element name="Name" type="xsd:string"/>
		<element name="Editable" type="xsd:boolean"/>
		<element name="Mandatory" type="xsd:boolean"/>
		<element name="Restricted" type="xsd:boolean"/>
		<element name="Refresh" type="xsd:boolean"/>
	</all>
</complexType>

This indicates that when the field is changed by the end-user, the GetDialog service needs to be called by client applications to redraw the dialog. The core server sets this flag for the Brand, overrule Issue and Status fields, which represents the current behavior.

Multiple objects support [since 9.2]

Since Enterprise Server 9.2, a new parameter ‘MultipleObjects’ is added to the request. This boolean field can be used to specify whether the dialog is being drawn for a single object (false or nil) or for multiple objects (true).

For backwards compatibility with older clients, the parameter is optional. A request without this parameter is interpreted as a Set Properties operation for a single object.

Based on the parameter value, advanced business rules may apply when determining the dialog options, only returning those properties that apply when handling multiple objects.

Dropped support for the Overrule Brand option [since 10.7.0]

Since Enterprise Server 10.7.0 the option to determine if an Issue should have its own Categories, Workflow, and User Authorization definitions is removed. References to this option in both the Admin as the Workflow services will result in an error (Missing function parameter (S1000)).