Creating Objects with Active Keys

Once a key has been activated the following options are available for creating and/or updating objects:

  • STEPXML
  • Web Services APIs
  • Web UI Simple Importer
  • Workbench

STEPXML

Once a key has been activated, external systems can identify objects in STEP (with generated Keys) via their resolved key values or by providing values for the key attributes. In the example below, the key 'EAN' is active, and Sales Item Product objects can now be updated by external systems that only know the EAN of an object and not its STEP ID.

In STEPXML a special 'KeyValue' element is available but it is also possible to identify a Sales Item by providing the value for the EAN attribute. Both STEPXML snippets shown below would update the existing Sales Item with EAN 6725372937625.

Copy 
<?xml version="1.0" encoding="utf-8"?>
<STEP-ProductInformation ContextID="GL" WorkspaceID="Main">
  <Products>
    <Product>
      <KeyValue KeyID="EAN">6725372937625</KeyValue>
      <Values>
        <Value AttributeID="HE Color">Black</Value>
      </Values>
    </Product>
  </Products>
</STEP-ProductInformation>    
Copy 
<?xml version="1.0" encoding="utf-8"?>
<STEP-ProductInformation ContextID="GL" WorkspaceID="Main">
  <Products>
    <Product>
      <Values>
        <Value AttributeID="EAN">6725372937625</Value>
        <Value AttributeID="HE Color">Black</Value>
      </Values>
    </Product>
  </Products>
</STEP-ProductInformation>    

Note: If no object with the specified key exists, STEP will try to create a new object and thus Object Types selected for key definitions should have Auto ID configured. Apart from this, successful creation depends on parent information and Object Type information being supplied in the file. The KeyValue element data is only used for matching and you cannot set a key using it. Also, if there is a mismatch between the KeyValue value and actual attribute values, the attribute? values take precedence.

When creating new objects via a STEPXML import file, if the same unique key value exists more than once, the system will ignore the duplicate unique key, skip object creation of the duplicate, and proceed with the import. Additionally, if different unique key values exist for the same object in a STEPXML file, no object is created and an informative error message displays letting the user know how to fix the problem before importing again.

For Generic XML and the tabular formats, STEP IDs can be left out and an object identified via values for key attributes. Because the 'Identify Destination' step of the Import Manager does not support Keys and objects, items in this step incorrectly can be identified as being new.

For more information about creating objects using STEPXML, refer to the Create Objects in STEPXML topic (here) within the STEPXML Format documentation.

Web Services APIs

Both SOAP APIs and REST APIs have key requests available. Refer to the respective sections below for details.

SOAP APIs

For the SOAP API a 'queryByKey' request is available:

Copy 
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://stibo.com/step/ws/step/1.0" xmlns:ns1="http://stibo.com/step/ws/types/1.0">
  <soapenv:Header/>
  <soapenv:Body>
    <ns:queryByKeyRequest>
      <ns:accessContext>
        <ns1:userName>******</ns1:userName>
        <ns1:password>******</ns1:password>
      </ns:accessContext>
      <ns:keyConditions>
        <ns1:keyExternalID>EAN</ns1:keyExternalID>
        <ns1:key>6725372937625</ns1:key>
        <ns1:type>product</ns1:type>
      </ns:keyConditions>
    </ns:queryByKeyRequest>
  </soapenv:Body>
</soapenv:Envelope>   

REST APIs

Similarly, for REST, an “objectbykey” resource is available:

Copy 
GET http://[host]/restapi/objectbykey/EAN/6725372937625?context=Context1&workspace=Main   

Web UI Simple Importer

New objects with active keys can be created and/or updated using the Simple Importer Widget within Web UI. For more information, refer to the Simple Importer Widget topic (here) within the Using a Web UI documentation.

Workbench

When you use the workbench to create new products of an object type for which active keys exist, the Create Product dialog includes editors for supplying values for key attributes.

The attribute value field can be left blank in which case no key will be generated. As mentioned above, a Key will be generated (and the editor field locked) once a value has been set.

When you have entered all values, STEP tries to generate a key for the product. If this fails because the key is already being used by another product, a dialog is displayed with information about the problem.

When a product of an object type for which an active keys exists is imported, a key is generated provided that all key attributes are populated. Any key conflicts are reported in the Execution report, and the new product will not be created.

Note: A product can be created without entering the key attribute value, and the value can be added later.