PUT imcc/v1/import/record/

Submit record(s) to add/update, in user defined XML form. IMCC will transform this into ImagenRecord(s) using the specified XSL (eXtensible Stylesheet Language) mapping file and add to the database. Records may also be updated with this method. This call will expect the body of the call to have Content-Type "text/xml" or "application/xml".

Resource URL

https://{MEDIACONTROLCENTRE_HOST}[:PORT]/imcc/v1/import/record/

Resource Information


Response formats	XML
Requires authentication?	Yes (user context only)
Required scope	modifyUsersData

Additional Request Headers

`X-Imagen-Pathprefix`

optional

The path to the directory where the media you want to ingest is stored. If specified then IMCC will add this to the paths specified in the media object elements, if not specified these paths will be used as is.

The X-Imagen-Pathprefix value should be a fully qualified path and can be a UNC path, local path, HTTP URL or HTTPS URL.

For example, if the Media Element OriginalFile is "koala.jpg" and the X-Imagen-Pathprefix is "\\testing\myshare\" then StorageService will look for the file in "\\testing\myshare\koala.jpg", but if the Media Element OriginalFile is "01234.mpg" and the X-Imagen-Pathprefix is "\\testing\myvideos\record_" then StorageService will look for the file in "\\testing\myvideos\record_01234.mpg".

Parameters

Optional parameters should be supplied as query parameters.

`Mapping`

required

Name of the mapping file to use to transform the XML body into ImagenRecord(s). You can get a list of valid mapping files by calling GET mappings. Contact your administrator to find out what your source XML should look like given the mapping file(s) you can use, and which input fields are required in your source XML.

`timeout`

optional

Timeout in seconds to wait to see if the import will finish after which a progress response will be returned. If Timeout is not specified or is < 0 then this call is synchronous and will wait indefinitely for the import to finish.

`guid`

optional

GUID for the import task - if not specified then IMCC will generate one.

`workflow`

optional

Workflow Name or ID. This must be specified if you wish any new media elements in the records to be ingested using this workflow. You can get a list of workflows by calling GET workflows

`resourcegroup`

optional

Resource group to use for ingest. If not specified then IMCC will use its first one.

`searchfield`

optional

Search field to use for this import. This must be the actual field name in the database that you would like to use to uniquely find and update existing record(s). If Record ID is found in the resultant XML this will take priority. If neither is specified or no record is found with the specified value for searchField then records will be added. If more than one record is found with the specified value for searchField then the import task will fail with relevant error.

Response

Returns progress of the import task or standard error response on failure.

Note that DatabaseJob State can be:- 0 - Waiting, 1 - Processing, 2 - Completed, 3 - Failed.

DatabaseJob type will always be 2 for import record tasks.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <DatabaseJob GUID="" State="2" Type="2">
      <Progress></Progress><!-- Progress for this task as a percentage-->
      <Error>
         <Message></Message><!-- Error message filled in if there's a failure -->
         <Details></Details><!-- Further error details if there are any -->
      </Error>
      <Import><!-- Note that even if the import fails this may include details of any records which were successfully imported -->
         <NumRecords></NumRecords><!-- Number of records which are being added/updated-->
         <ImagenRecords>
            <ImagenRecord ID=""><!-- list of ImagenRecords that have been added/updated with their ID and any added/modified MediaObjects-->
               <MediaObjects>
                  <MediaObject ID="" />
                  <StoreJob ID="" /><!-- ID of ingest job created when the media object was imported-->
               </MediaObjects>
            </ImagenRecord>           
         </ImagenRecords>
      </Import>
      <FailedImport>
         <NumRecords></NumRecords><!-- Number of records which failed to import-->
         <FailedImagenRecords>
            <ImagenRecord ID=""><!-- list of ImagenRecords that failed to import-->
               <ImportErrorCode></ImportErrorCode><!-- Error code -->
               <ImportError></ImportError><!-- Details of why this record failed to import -->
               <MediaObjects>
                  <MediaObject ID="" />
               </MediaObjects>
            </ImagenRecord>
         </FailedImagenRecords>
      </FailedImport>
   </DatabaseJob>
</Response>

Examples


Create a record
Create a record and ingest an image
Update records by ID
Update a record by searching

Create Record Example

This will create a record with Title = "A koala" and Creation_Date = "2015-01-01 11:00:00"

URL Format: https://{MEDIACONTROLCENTRE_HOST}[:PORT]/imcc/v1/import/record/{MAPPING_FILE}/

curl -i -H "X-Imagen-API-Key: {APPLICATION API KEY}" \
   -H "Authorization: Bearer {ACCESS_TOKEN}" \
   -H "Content-Type: text/xml" \
   -X PUT -T "{IMPORT XML FILE}" \
   "https://{MEDIACONTROLCENTRE_HOST}[:PORT]/imcc/v1/import/record/exampleMapping/"

Example import XML file:

<?xml version="1.0" encoding="UTF-8"?>
<MyRecord>
   <MyDescription>A koala</MyDescription>
   <StartDate>2015-01-01</StartDate>
   <StartTime>11:00</StartTime>
</MyRecord>

Example mapping file:

This assumes your administrator has added a mapping file to your MediaControlCentre which is of the following format. You will need to contact your administrator to find out what your source XML should actually look like for the mapping file you are using.

<?xml version="1.0" encoding="utf-8"?>
<xsl:stylesheet version="1.0" exclude-result-prefixes="msxsl" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:msxsl="urn:schemas-microsoft-com:xslt">
   <xsl:output method="xml" indent="yes"/>
   <xsl:template match="/">
      <Records>
         <xsl:for-each select="MyRecord">
            <ImagenRecord>
               <xsl:if test="RecordID != ''">
                  <xsl:attribute name="ID">
                     <xsl:value-of select="RecordID"/>
                  </xsl:attribute>
               </xsl:if>
               <Fields>
                  <xsl:if test="MyIDField != ''">
                     <xsl:element name="guid">
                        <xsl:value-of select="MyIDField"/>
                     </xsl:element>
                  </xsl:if>
                  <xsl:if test="MyDescription != ''">
                     <xsl:element name="Title">
                        <xsl:value-of select="MyDescription"/>
                     </xsl:element>
                  </xsl:if>
                  <xsl:if test="StartDate != ''">
                     <xsl:if test="StartTime != ''">
                        <xsl:element name="Creation_Date">
                           <xsl:value-of select="StartDate"/>
                            <xsl:text> </xsl:text>
                           <xsl:value-of select="StartTime"/>
                        </xsl:element>
                     </xsl:if>
                  </xsl:if>
               </Fields>
               <xsl:if test="OriginalFile != ''">
                  <MediaObject>
                     <xsl:choose>
                        <xsl:when test="SourceType = 'Radio'">
                           <xsl:attribute name="MediaType">Audio</xsl:attribute>
                        </xsl:when>
                        <xsl:when test="SourceType = 'Image'">
                           <xsl:attribute name="MediaType">Image</xsl:attribute>
                        </xsl:when>
                        <xsl:otherwise>
                           <xsl:attribute name="MediaType">Video</xsl:attribute>
                        </xsl:otherwise>
                     </xsl:choose>
                     <xsl:attribute name="ID">-1</xsl:attribute>
                     <xsl:if test="StartTime != ''">
                        <xsl:element name="TimecodeFormat">Smpte_25</xsl:element>
                        <xsl:element name="BaseTimecode">
                           <xsl:value-of select="StartTime"/>
                           <xsl:text>:00</xsl:text>
                        </xsl:element>
                     </xsl:if>
                     <xsl:element name="State">new</xsl:element>
                     <xsl:element name="MediaElement">
                        <xsl:choose>
                           <xsl:when test="SourceType = 'Radio'">
                              <xsl:attribute name="MediaType">Audio</xsl:attribute>
                           </xsl:when>
                           <xsl:when test="SourceType = 'Image'">
                              <xsl:attribute name="MediaType">Image</xsl:attribute>
                           </xsl:when>
                           <xsl:otherwise>
                              <xsl:attribute name="MediaType">Video</xsl:attribute>
                           </xsl:otherwise>
                        </xsl:choose>
                        <xsl:attribute name="Index">0</xsl:attribute>
                        <xsl:element name="OriginalFile">
                           <xsl:value-of select="OriginalFile"/>
                        </xsl:element>
                     </xsl:element>
                  </MediaObject>
               </xsl:if>
            </ImagenRecord>
         </xsl:for-each>
      </Records>
   </xsl:template>
</xsl:stylesheet>

Example Result

<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <DatabaseJob GUID="A7162165-CDEB-5E4E-A8AC-22AFF389C9C4" State="2" Type="2">
      <Progress>100</Progress>      
      <Import>
         <NumRecords>1</NumRecords>
         <ImagenRecords>
            <ImagenRecord ID="123456"></ImagenRecord>           
         </ImagenRecords>
      </Import>
   </DatabaseJob>
</Response>

Ingest Image Example

This will create a record with an image media object and store the image (here \\testing\myshare\koala.jpg) itself.

URL Format: https://{MEDIACONTROLCENTRE_HOST}[:PORT]/imcc/v1/import/record/{MAPPING_FILE}?timeout={TIMEOUT}&guid={GUID}&workflow={WORKFLOW}&resourcegroup={RESOURCE_GROUP}

curl -i -H "X-Imagen-API-Key: {APPLICATION API KEY}" \
   -H "Authorization: Bearer {ACCESS_TOKEN}" \
   -H "Content-Type: text/xml" \
   -H "X-Imagen-Pathprefix: \\testing\myshare\" \
   -X PUT -T "{IMPORT XML FILE}" \
   "https://{MEDIACONTROLCENTRE_HOST}[:PORT]/imcc/v1/import/record/exampleMapping?timeout=2&guid=A7162165-CDEB-5E4E-A8AC-22AFF389C9C4&workflow=IngestImage&resourcegroup=Local"

Example import XML file:

<?xml version="1.0" encoding="UTF-8"?>
<MyRecord>
   <OriginalFile>koala.jpg</OriginalFile>
   <MyDescription>A koala</MyDescription>
   <StartDate>2015-01-01</StartDate>
   <StartTime>11:00</StartTime>
   <SourceType>Image</SourceType>
</MyRecord>

Mapping file:

See mapping file

Example Result

<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <DatabaseJob GUID="A7162165-CDEB-5E4E-A8AC-22AFF389C9C4" State="2" Type="2">
      <Progress>100</Progress>      
      <Import>
         <NumRecords>1</NumRecords>
         <ImagenRecords>
            <ImagenRecord ID="123456">
               <MediaObjects>
                  <MediaObject ID="125" />
                  <StoreJob ID="FD3CF753-3496-4F0E-801A-5150C02F9357"/>
               </MediaObjects>
            </ImagenRecord>           
         </ImagenRecords>
      </Import>
   </DatabaseJob>
</Response>

Update Records Example

This will update record 2 to have Title = "New record title 2" and record 4 to have Title = "New record title 4"

URL Format: https://{MEDIACONTROLCENTRE_HOST}[:PORT]/imcc/v1/import/record/{MAPPING_FILE}

curl -i -H "X-Imagen-API-Key: {APPLICATION API KEY}" \
   -H "Authorization: Bearer {ACCESS_TOKEN}" \
   -H "Content-Type: text/xml" \
   -X PUT -T "{IMPORT XML FILE}" \
   "https://{MEDIACONTROLCENTRE_HOST}[:PORT]/imcc/v1/import/record/exampleMapping"

Example import XML file:

<?xml version="1.0" encoding="UTF-8"?>
<MyRecord>
   <RecordID>2</RecordID>
   <MyDescription>New record title 2</MyDescription>
</MyRecord>
<MyRecord>
   <RecordID>4</RecordID>
   <MyDescription>New record title 4</MyDescription>
</MyRecord>

Mapping file:

See mapping file

Example Result

<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <DatabaseJob GUID="A7162165-CDEB-5E4E-A8AC-22AFF389C9C4" State="2" Type="2">
      <Progress>100</Progress>      
      <Import>
         <NumRecords>2</NumRecords>
         <ImagenRecords>
            <ImagenRecord ID="2"></ImagenRecord>           
            <ImagenRecord ID="4"></ImagenRecord>           
         </ImagenRecords>
      </Import>
   </DatabaseJob>
</Response>

Update By Search Example

This will update record with guid = "33DF5AA3-1684-4da1-9168-0B143ED2B2E6" to have Title = "New updated title"

URL Format: https://{MEDIACONTROLCENTRE_HOST}[:PORT]/imcc/v1/import/record/{MAPPING_FILE}?searchfield={SEARCH_FIELD}

curl -i -H "X-Imagen-API-Key: {APPLICATION API KEY}" \
   -H "Authorization: Bearer {ACCESS_TOKEN}" \
   -H "Content-Type: text/xml" \
   -X PUT -T "{IMPORT XML FILE}" \
   "https://{MEDIACONTROLCENTRE_HOST}[:PORT]/imcc/v1/import/record/exampleMapping?searchfield=guid"

Example import XML file:

<?xml version="1.0" encoding="UTF-8"?>
<MyRecord>
   <MyIDField>33DF5AA3-1684-4da1-9168-0B143ED2B2E6</MyIDField>
   <MyDescription>New updated title</MyDescription>
</MyRecord>

Mapping file:

See mapping file

Example Result

<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <DatabaseJob GUID="A7162165-CDEB-5E4E-A8AC-22AFF389C9C4" State="2" Type="2">
      <Progress>100</Progress>      
      <Import>
         <NumRecords>1</NumRecords>
         <ImagenRecords>
            <ImagenRecord ID="12345"></ImagenRecord>       
         </ImagenRecords>
      </Import>
   </DatabaseJob>
</Response>

Imagen API Documentation

PUT imcc/v1/import/record/

Resource URL

Resource Information

Additional Request Headers

X-Imagen-Pathprefix

Parameters

Mapping

timeout

guid

workflow

resourcegroup

searchfield

Response

Examples

Create Record Example

Example mapping file:

Example Result

Ingest Image Example

Mapping file:

Example Result

Update Records Example

Mapping file:

Example Result

Update By Search Example

Mapping file:

Example Result

`X-Imagen-Pathprefix`

`Mapping`

`timeout`

`guid`

`workflow`

`resourcegroup`

`searchfield`