StoreFront Store Services API

Subscriptions service

August 16, 2023

Contributed by:

This service allows resources to be subscribed and unsubscribed, and to have data associated with each subscription.

Request

URL (indicative only) and content-type	Method	Description
/resources/v2/subscriptions/{resourceId} application/vnd.citrix.subscriptionupdate+xml	POST	Action depends upon updateType attribute value: subscribe: Try to subscribe to the resource. This may create a new subscription (if one does not already exist) and by default will set the subscription to the subscribed state (although later extensions may complicate this behavior). unsubscribe : Try to unsubscribe from the resource. This may delete the subscription and by default will set the subscription to the notSubscribed state (although later extensions may complicate this behavior). update: Update the data associated with the subscription. This should succeed independent of future extensions, although will return 404 (Not Found) if no subscription exists.

Parameter	Description
{resourceId}	The identifier of the associated resource. This is unique to the instance of the service.

Note:

The URLs given above are for illustrative purposes only. The actual URL used in a request should be obtained from the results of an enumeration request (eg /resources/v2/ or /resources/v2/{id}).

Request data

The POSTed requests are XML, described by the schema: /Schemas/Subscriptions.xsd, with top level element subscriptionUpdate.

Response

Response Code (and friendly name)	Description
200 (OK)	Subscription added/removed successfully or conflict occurred, the response content-type indicates which. See Success Response Content and Conflict Response Content sections below. The conflict response is returned in any of the following cases: A request is made to subscribe to a resource in an incompatible state (e.g. subscribed), A request is made to unsubscribe from a resource in an incompatible state (e.g. unsubscribed), A request is made to update data for a resource with no subscription record, An unspecified data conflict occurs due to clash with another simultaneous request, or An extension (e.g. workflow integration) indicates a conflict in state (see relevant extension specification for details).
202 (Accepted)	The request to subscribe/unsubscribe has been accepted, however there is workflow associated with the subscription/unsubscription which must be completed before the action will be complete.
400 (Bad Request)	Missing {id} value or malformed data in the request body.
401 (Unauthorized)	Bad/Missing security token (see CitrixAuth Authentication Scheme document [3])
403 (Forbidden)	The request token did not contain a user security identifier claim (this is required to give a unique identifier for the user for recording subscriptions)
404 (Not Found)	Subscriptions are not enabled or the supplied resourceId does not refer to a resource visible to the requesting user. The reason is indicated by the X-Citrix-Error-Reason header value in the HTTP response: ResourceNotFound: No resource was found for the requesting user for the specified id. SubscriptionsDisabled: Subscriptions are not enabled for the Store service. (Not expected unless advanced customization is performed on the server.) SubscriptionsReadOnly: Subscriptions are read only for the Store service
503 (Service Unavailable)	An extension is temporarily unable to contact a service it requires to contact as part of the subscription process (see relevant extension specification for details)

Success response content

In the case that a successful response (HTTP status code 200 (OK)) is returned, the response body contains an XML document, described by the schema: /Schemas/Subscriptions.xsd with root node subscriptionResult. The response contains the subscription and resource ids, current status of the subscription, and also properties that contain data relating to the subscription action (this data is empty except in the case of extensions):

Response Format	Request Accept /Response Content-Type Header
XML	application/vnd.citrix.subscriptionresult+xml

Note:

The data Xml element of the subscription result may contain properties that relate to the status change that has occurred as a result of the subscribe/unsubscribe action. This is intended as an extension mechanism.

No account is made in the subscribe/unsubscribe actions what permissions, if any, the requesting user has on the resource identified by {resourceId}, other than that it is visible to that user.

Subscription status

Status	Description
notSubscribed	The resource is not subscribed.
subscribed	The resource is subscribed.
approved	Workflow has run and the user has been granted permission to use the resource. The subscription is awaiting user acknowledgment.
denied	Workflow has run and the user has been denied permission to use the resource. The subscription is awaiting user acknowledgment.
All other values	Workflow is running to determine whether the user may use the resource.

Example: Successful unsubscription

Request

POST http://www.example.com/Citrix/Store/resources/v2/subscriptions/Q2l0cm...Q- HTTP/1.1 Authorization: CitrixAuth H4sIA....
Host: www.example.com
Accepts: application/vnd.citrix.subscriptionresult+xml,
application/vnd.citrix.subscriptionconflict+xml Content-Type: application/vnd.citrix.subscriptionupdate+xml Content-Length: 269
<!--NeedCopy-->

<?xml version="1.0" encoding="utf-8"?>
<subscriptionUpdate xmlns="http://citrix.com/delivery-services/2-0/subscriptions"
       updateType="unsubscribe"
       updateDataMode="merge">
  <clientName>clientname</clientName>
</subscriptionUpdate>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Cache-Control: public, no-store, max-age=0
Content-Type: application/vnd.citrix.subscriptionresult+xml Date: Wed, 16 Feb 2011 17:31:43 GMT
Content-Length: xxxx
<!--NeedCopy-->

<?xml version="1.0" encoding="utf-8"?>
<subscriptionResult xmlns="http://citrix.com/delivery-services/2-0/subscriptions">
<subscriptionId>4C34BB98E543F084BAA33696C5659F63</subscriptionId> <resourceId>Citrix.MPS.App.Farm 1.Notepad</resourceId> <status>notSubscribed</status>
<data />
</subscriptionResult>
<!--NeedCopy-->

Example: Successful update of subscription data

This is an example of a successful update of the data associated with a subscription. The property IDs and values are arbitrary from the perspective of the resources service.

Request

POST http://www.example.com/Citrix/Store/resources/v2/subscriptions/Q2l0cm...Q- HTTP/1.1 Authorization: CitrixAuth H4sIA....
Host: www.example.com
Accepts: application/vnd.citrix.subscriptionresult+xml,
application/vnd.citrix.subscriptionconflict+xml Content-Type: application/vnd.citrix.subscriptionupdate+xml Content-Length: xxxx
Expect: 100-continue
Connection: Keep-Alive
<!--NeedCopy-->

<?xml version="1.0" encoding="utf-8"?>
<subscriptionUpdate xmlns="http://citrix.com/delivery-services/2-0/subscriptions"
       updateType="update"
       updateDataMode="merge" >
  <data>
    <property key="Data1Key">
      <value>Data1 Value1</value>
      <value>Data1 Value2</value>
    </property>
  </data>
  <clientName>clientname</clientName>
</subscriptionUpdate>
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Cache-Control: public, no-store, max-age=0
Content-Type: application/vnd.citrix.subscriptionresult+xml Content-Length: xxxx
<!--NeedCopy-->

<?xml version="1.0" encoding="utf-8"?>
<subscriptionResult xmlns="http://citrix.com/delivery-services/2-0/subscriptions">
<subscriptionId>4C34BB98E543F084BAA33696C5659F63</subscriptionId> <resourceId>Citrix.MPS.App.Farm 1.Notepad</resourceId> <status>subscribed</status>
<data />
</subscriptionResult>
<!--NeedCopy-->

Conflict response content

In the case that a conflict is returned (HTTP status code 200 (OK)), a response potentially containing data pertaining to the conflict is returned in the response body:

Response Format	Request Accept /Response Content-Type Header
XML	application/vnd.citrix.subscriptionconflict+xml

The subscription result content is XML, described by the schema: /Schemas/Subscriptions.xsd with root node subscriptionConflict.

Note:

The subscriptionconflict content type is intended to allow for extension, and will only contain properties in the case of extensions (e.g. workflow integration).

Conflict reason

The conflict response contains a reason attribute. The possible reason values are an open set allowing for workflow-integration-specific values in the future. The values defined in the base system are:

Reason value	Meaning
GeneralDataStoreConflict	An undetermined conflict within the subscription data storage (typically due to transaction conflicts).
MissingSubscription	A conflict due to a missing subscription. (e.g. an attempt to unsubscribe or update a subscription to a resource that has never been subscribed.)
ConflictingSubscriptionState	A conflict due to the state of an existing subscription. (e.g. an attempt to subscribe to a resource with a subscription with status subscribed.)
GeneralWorkflowConflict	A conflict caused by an undetermined conflict within the workflow system.

Example: Unsuccessful subscription

An example of an attempted subscription that is unsuccessful because the resource is already subscribed.

The subscription, if successful, would have associated a client-specific property named “dazzle:path” with the subscription. The property ID and value are arbitrary from the perspective of the resources service.

Request

POST http://www.example.com/Citrix/Store/resources/v2/subscriptions/Q2l0cm...Q- HTTP/1.1 Authorization: CitrixAuth H4sIA....
Host: www.example.com
Accepts: application/vnd.citrix.subscriptionresult+xml,
application/vnd.citrix.subscriptionconflict+xml Content-Type: application/vnd.citrix.subscriptionupdate+xml Content-Length: xxxx
<!--NeedCopy-->

<?xml version="1.0" encoding="utf-8"?>
<subscriptionUpdate xmlns="http://citrix.com/delivery-services/2-0/subscriptions"
       updateType="subscribe"
       updateDataMode="merge" />
<!--NeedCopy-->

Response

HTTP/1.1 200 OK
Cache-Control: public, no-store, max-age=0
Content-Type: application/vnd.citrix.subscriptionconflict+xml Content-Length: xxxx
<!--NeedCopy-->

<?xml version="1.0" encoding="utf-8"?>
<subscriptionConflict xmlns="http://citrix.com/delivery-services/2-0/subscriptions"
       reason="ConflictingSubscriptionState" >
 <data />
</subscriptionConflict>
<!--NeedCopy-->

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Was this helpful

Subscriptions service

August 16, 2023

Contributed by:

August 16, 2023

Contributed by:

Subscriptions service

Request

Request data

Response

Success response content

Subscription status

Example: Successful unsubscription

Request

Response

Example: Successful update of subscription data

Request

Response

Conflict response content

Conflict reason

Example: Unsuccessful subscription

Request

Response

In this article