Updating Service Provider records URLs in batch

You can update all of your Service Provider records at once when your Service Provider is rehosted or when you are required to change their URLs. For this purpose, you can send a single HTTP request that includes a regular expression pattern of remapping to be applied to all stored URLs.

About this task

Only user or groups that are mapped to the RegistryProviderAdminRole and RegistryAdminRole roles can send requests to the batch service.

The update of Service Provider records in batch is implemented by using the OSLC Automation Specification. The HTTP request is sent as an Automation Request.

With this batch operation, you can update all URL property values in a Service Provider record:
  • sourceRecord of the Service Provider record, which corresponds to the about field. This field was provided when you registered the Service Provider record.
  • creation of any CreationFactory of the selected Service Provider record.
  • queryBase of any QueryCapability of the selected Service Provider record.
  • OAuth URLs.
  • Resource Shape URLs.
  • Custom properties with URL values.

Procedure

  1. Send an HTTP HEAD request to the Provider Registry collection URL. For example, https://oslc-registry/oslc/pr/collection.
  2. Locate the Provider Registry automation collection URL in the Link header of the response. The automation collection URL is identified by the http://jazz.net/ns/ism/registry#provider-automation-collection relationship. For example: 
    <https://oslc-registry/oslc/rr/collection>; 
rel="http://jazz.net/ns/ism/registry#resource-record-collection",
<https://oslc-registry/oslc/rr/registration/collection>; 
rel="http://jazz.net/ns/ism/registry#registration-record-collection",
<https://oslc-registry/oslc/rr/shapes/collection>; 
rel="http://jazz.net/ns/ism/registry#resource-shape-collection",
<https://oslc-registry/oslc/rr/operations/collection>; 
rel="http://jazz.net/ns/ism/registry#resource-automation-collection",
<https://oslc-registry/oslc/pr/operations/collection>; 
rel="http://jazz.net/ns/ism/registry#provider-automation-collection"
  3. Set the Accept HTTP header to define the media type in which you want to get the resource representation. Possible values for the media types are as follows:
    • application/xml to get an abbreviated RDF/XML representation of the resource.
    • application/rdf+xml to get an expanded RDF/XML representation of the resource.
    If you do not specify this header, you get a resource represented in abbreviated RDF/XML format by default.
  4. Optional: Specify the Accept-Language HTTP header with the preferred language for the error response to your request. See Language definition.
  5. Construct the Automation Request RDF payload with the parameters to define the Service Provider records to be updated. Ensure that you specified the URL http://jazz.net/ns/ism/registry#UpdateProviderRecordUrls as the value for the oslc_auto:executesAutomationPlan property.

    For example:

    <?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dcterms="http://purl.org/dc/terms/"
  xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
  xmlns:crtv="http://open-services.net/ns/crtv#"
  xmlns:rr="http://jazz.net/ns/ism/registry#"
  xmlns:oslc="http://open-services.net/ns/core#"
  xmlns:oslc_auto="http://open-services.net/ns/auto#">
    <oslc_auto:AutomationRequest>
       <dcterms:title>Update Provider Record URLs</dcterms:title>
       <dcterms:identifier>UpdateProviderRecordUrls</dcterms:identifier>
       <oslc_auto:inputParameter>
         <oslc_auto:ParameterInstance>
           <oslc:name>filter</oslc:name> <!-- optional filter parameter -->
           <rdf:value>oslc.where=dcterms:title="TBSM 1 OSLC Provider"</rdf:value>
         </oslc_auto:ParameterInstance>
       </oslc_auto:inputParameter>
       <oslc_auto:inputParameter>
         <oslc_auto:ParameterInstance>
           <oslc:name>pattern</oslc:name> 
	<!-- regex describing pattern to be replaced, supports Java Pattern regex syntax -->
           <rdf:value>.*\.mylab\.mylocale\.ibm\.com</rdf:value>
         </oslc_auto:ParameterInstance>
       </oslc_auto:inputParameter>
       <oslc_auto:inputParameter>
         <oslc_auto:ParameterInstance>
           <oslc:name>replacement</oslc:name> 
	<!-- string which replaces all instances of the specified pattern -->
           <rdf:value>frs01.mylab.mylocale.ibm.com</rdf:value>
         </oslc_auto:ParameterInstance>
       </oslc_auto:inputParameter>
       <oslc_auto:executesAutomationPlan 
rdf:resource="http://jazz.net/ns/ism/registry#UpdateProviderRecordUrls"/>
    </oslc_auto:AutomationRequest>
</rdf:RDF>

    With the optional filter parameter, you can specify the Service Provider records to be updated by using the OSLC query syntax. Only the oslc.where parameter is supported in this case.

    The pattern parameter specifies the regular expression pattern to which the URLs that match are replaced by the value on the replacement parameter.

  6. Send an HTTP POST request with this payload to the Batch Creation Factory URL.

Results

The HTTP 200 (OK) status code indicates that the request was successfully processed.

However, even when the HTTP 200 status code is returned, the operation might not entirely succeed. Any failure that you get while the operation is running is indicated by the verdict of failed in the response.

The payload that is returned contains an indication of success or failure, and a parameter that indicates the number of Service Provider records updated.

As you can see in this response sample, the oslc:name parameter contains the error value. For example:
<rdf:RDF
  xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
  xmlns:dcterms="http://purl.org/dc/terms/"
  xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
  xmlns:rr="http://jazz.net/ns/ism/registry#"
  xmlns:oslc="http://open-services.net/ns/core#"
  xmlns:oslc_auto="http://open-services.net/ns/auto#">
	<oslc_auto:AutomationResult>
		<dcterms:title>Update Provider Record URLs</dcterms:title>
		<dcterms:identifier>UpdateProviderRecordURLs</dcterms:identifier>
		<oslc_auto:verdict rdf:resource="http://open-services.net/ns/auto#failed"/>
		<oslc_auto:state rdf:resource="http://open-services.net/ns/auto#complete"/>
		<oslc_auto:reportsOnAutomationPlan rdf:resource="http://www.ibm.com/xmlns
/prod/tivoli/registry#UpdateProviderRecordUrls"/>
		<oslc_auto:contribution>
			<oslc_auto:ParameterInstance>
				<oslc:name>error</oslc:name>
               <rdf:value>
                    <oslc:Error>
                        <oslc:extendedError></oslc:extendedError>
                        <oslc:message>CTJFK0103E Incoming request from IP 9.13.116.221 
did not end successfully. The Registry Services application encountered an internal error 
while processing the registration record query request for the given parameters: 
"oslc.where=invalid". The specific reason for this error is: CTJFK0106E The Registry Services 
application encountered a syntax error while processing the oslc.where query: "invalid" at the
 position: 0.</oslc:message>
                        <oslc:statusCode>500</oslc:statusCode>
                    </oslc:Error>
               </rdf:value>
	</oslc_auto:ParameterInstance>
		</oslc_auto:contribution>
	</oslc_auto:AutomationResult>
</rdf:RDF>

This response payload contains the oslc_auto:AutomationResult property.

If an error occurs after the replacement, the Registry Services rolls back the changes and includes a failed verdict in the automation result.

The oslc:Error property contains information about the error.

If the HTTP request fails, the HTTP response contains the appropriate status code and error message. For more information, see Application runtime.

Parent topic: Provider Registry