Importing Data Using the XML API Import Tool

Required XML FY2020 Header For Data XML Files

<?xml version="1.0" encoding="UTF-8"?>
<hmis:Sources xmlns:airs="http://www.clarityhumanservices.com/schema/2020/1/AIRS_3_0_mod.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:hmis="http://www.clarityhumanservices.com/schema/2020/1/HUD_HMIS.xsd">
 <hmis:Source>

Required XML FY2020 Header For MAP XML Files

<?xml version="1.0" encoding="UTF-8"?>

<hmis:Sources xmlns:airs="http://www.clarityhumanservices.com/schema/2020/1/AIRS_3_0_mod.xsd" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns:hmis="http://www.clarityhumanservices.com/schema/2020/1/HUD_HMIS.xsd">

<hmis:Source>

Sending Import Request

$fullPathToXmlFile = 'Your-XML-File.xml';
$autUserName = 'YOUR-API-USER-KEY';
$autUserPassword = 'YOUR-API-USER-PASSWORD';
$apiUrl = 'https://api-YOUR-INSTANCE-NAME.clarityhs.com/import/xml/data';
$client = new XmlImportClient($autUserName, $autUserPassword, $apiUrl);
$result = $client->importFile($fullPathToXmlFile);



class XmlImportClient {
    /**
     * @var string full path to file being imported. File should not be encrypted!
     */
    protected $file;
    /**
     * @var string HTTP auth user name
     */
    protected $username;
    /**
     * @var string HTTP auth password.
     */
    protected $password;
    /**
     * @var string url to target instance
     */
    protected $requestUrl;

    public function __construct($username, $password, $requestUrl) {
        $this->username = $username;
        $this->password = $password;
        $this->requestUrl = $requestUrl;
    }

    /**
     * Provides import of XML file to Clarity instance.
     *
     * @var string $file full path to file that should be imported.
     *
     * @return mixed import result.
     */
    public function importFile($file) {
        set_time_limit(0);
        $this->file = $file;

        $request = $this->createRequest();

        $result = $this->sendRequest($request);

        return $result;
    }

    protected function createRequest() {
        $request = curl_init();
        $this->initRequestTarget($request);

        $this->attachFileToRequest($request);

        $this->attachImportPropertiesToRequest($request);

        $this->attachAutInfoToRequest($request);

        return $request;
    }

    protected function initRequestTarget($request) {
        $requestUrl = $this->requestUrl;
        curl_setopt($request, CURLOPT_URL, $requestUrl);
        curl_setopt($request, CURLOPT_TIMEOUT, 0);
        curl_setopt($request, CURLOPT_RETURNTRANSFER, 1);
    }

    protected function attachFileToRequest($request) {
        curl_setopt($request, CURLOPT_POST, true);
        $dataFile = $this->file;
        $fileName = basename($dataFile);
        $fileType = 'text/xml';
        $postData = array(
            'data_file' => curl_file_create($dataFile, $fileType, $fileName), // Available since PHP 5.5
        );
        curl_setopt($request, CURLOPT_POSTFIELDS, $postData);
    }

    protected function attachAutInfoToRequest($request) {
        curl_setopt($request, CURLOPT_USERPWD, $this->username . ':' . $this->password);
        curl_setopt($request, CURLOPT_SSL_VERIFYPEER, 0);
        curl_setopt($request, CURLOPT_SSL_VERIFYHOST, 0);
    }


    protected function attachImportPropertiesToRequest($request) {
        curl_setopt($request, CURLOPT_HTTPHEADER, array(
            'Standard-Version: 2020', // Indicates what standard to use
            'Content-Encrypted: 0', // Indicates that data is not encrypted and MCrypt should not be used
        ));
    }

    protected function sendRequest($request) {
        $result = curl_exec($request);
        if (!$result) {
            curl_close($request);
            throw new Exception('Unable to receive response from the Clarity instance.');
        }
        curl_close($request);
        return $result;
    }
}

  

Incoming XML Format

   <hmis:Sources
    xmlns:hmis="http://www.clarityhumanservices.com/schema/2020/1/HUD_HMIS.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  

XML 1.0 vs XML 1.1

  <!--Testing if DisabilityType is 8, before allowing use of TCellCountAvailable-->
  <xs:assert test="if (hmis:TCellCountAvailable) then boolean(hmis:DisabilityType/text()='8') else true()"/>

  <!--Testing if TCellCountAvailable is 1, before allowing use of TCellCount-->
  <xs:assert test="if (hmis:TCellCountAvailable/text()='1') then boolean(hmis:TCellCount) else (if (not(hmis:TCellCountAvailable/text()='1')) then (not(boolean(hmis:TCellCount))) else false())"/>

  <!--Testing if TCellCount is not null, before allowing use of TCellSource-->
  <xs:assert test="if (hmis:TCellCount) then boolean(hmis:TCellSource) else (if (not(hmis:TCellCount)) then (not(boolean(hmis:TCellSource))) else false())"/>

  <!--Testing if DisabilityType is 8, before allowing use of ViralLoadAvailable-->
  <xs:assert test="if (hmis:ViralLoadAvailable) then boolean(hmis:DisabilityType/text()='8') else true()"/>
		
  <!--Testing if ViralLoadAvailable is 1, before allowing use of ViralLoad-->
  <xs:assert test="if (hmis:ViralLoadAvailable/text()='1') then boolean(hmis:ViralLoad) else (if (not(hmis:ViralLoadAvailable/text()='1')) then (not(boolean(hmis:ViralLoad))) else false())"/>
		
  <!--Testing if  ViralLoad is not null, before allowing use of  ViralLoadSource-->
  <xs:assert test="if (hmis:ViralLoad) then boolean(hmis:ViralLoadSource) else (if (not(hmis:ViralLoad)) then (not(boolean(hmis:ViralLoadSource))) else false())"/>
   

<?xml version="1.0"  encoding="UTF-8"?>
<map:Map xmlns:map="http://www.clarityhumanservices.com/schema/2020/1/mapping.xsd">
    <Source>
        <SourceID>YOUR-Organization-ID</SourceID>
   </Source>
    <Programs>
        <Program>
            <ClarityID>677</ClarityID>  // Target Clarity Program ID
            <ExternalID>1</ExternalID>  // Source System Program ID
        </Program>
        <Program>
            <ClarityID>678</ClarityID>
            <ExternalID>2</ExternalID>
       </Program>
        <Program>
            <ClarityID>679</ClarityID>
            <ExternalID>3</ExternalID>
        </Program>
    </Programs>
    <ServiceItems>
        <ServiceItem>
            <ClarityID>370</ClarityID>  // Target Clarity Service Item ID
            <ExternalID>583</ExternalID> //Source System Service iD
        </ServiceItem>        
    </ServiceItems>
</map:Map>

RESTful XML API Web Interface

There maybe times either during testing or when you want to manually import your XML files, we have provide a Web Interface that allows you to import your XML Data files once you have uploaded your Mapping XML File.

IMPORT URL: https://rest-client.clarityhs.com

IMPORT OPTIONS:

STATUS URL: https://rest-client.clarityhs.com/site/status

Show Operations Drop-Down Options:

Rest-Client URL

To use the Web Interface you will require the information that is listed below:

The URL’s listed take you to one of three pages, Import Progress, Import Errors & Import Results. This XML response is generated every time a Mapping or Data XML file is import into the Clarity system via the rest API.

This information will be provided to you by your system administrator, please ensure you keep this information in a secure location as defined by your organization security policies.