COLLECTOR_FIELDS

Overview
The COLLECTOR_FIELDS entity allows you to input charges into the application before the mediation layer. When input this way the application will process this data using the same methods as if were to have collected it through the UI collector. This means the system will determine the appropriate entity to assign the charge to, as well as the correct rate, using pricing plans, rate classes, and product defaults.

Sucessfully processed collector field records will generate ACTIVITY entity records, as well and invoice item records, and invoices if a CURRENT one does not already exist.

In order for the system to correctly direct charges and assign rates, a couple things need to be setup beforehand. These two items are billing identifiers, and mapping a field to the billing components. Billing identifier must be unique to the billable entity, and configured to the correct service point. More information on billing identifiers can be found here. Any field can be mapped as a billing component identifer. This field must be unique to the product, and correctly configured in the billing component mapping section of the application. More information on this can be found here.

COLLECTOR_FIELD records are processed in bulk. Each load exists in an ACTIVITY_COLLECTOR_HISTORY record. When you begin to load records into the COLLECTOR_FIELD entity, the application will create an activity collector history record, which will be assigned to every record you create. The activity collector history session will close when you log out of web services or your session expires. Only when the activity collector history session is closed will the records process through the system and while this has not happened yet, the status of the newly loaded collector data will be in the PENDING LOGOUT status.

System Entity Name
COLLECTOR_FIELDS

Allowed Functions

Create Update Retrieve Delete Upsert
YES YES YES NO YES

 

Fields

Field Data Type Properties Description
ActivityCollectorObj ACTIVITY_COLLECTOR required, unique Object in which to enter the appropriate activity collector object.
ActivityCollectorId decimal required

Enter the ID of the activity collector these records will use to process.  More information on setting up an activity collector via webservices, please see here.  For more information on setting up an activity collector via the UI, please see here.

 

The setup from the activity collector will be responsible for mapping the components to the appropriate fields, as well as formatting the different fields.  Formatting can be important for date fields as they must contain an appropriate date mask.  The date mask will allow the field to be used as a date in the application as opposed to a string.

ActivityDate string   Enter the activity date for the record you are entering, this should be the date the usage record actually occured.
Ended string   If this record has an end date/time, enter this here.
OriginationCountryCode string  

For international type usage you can enter the origination value here.  This is used in conjuction with the international numbers.  When configured this allows you to specify rates based on external factors.

DestinationCountryCode string   For international type usage you can enter the destination value here.  This is used in conjuction with the international numbers.  When configured this allows you to specify rates based on external factors.
OverrideBuyCost string   If you want to override the buy cost specified at the billing component, you can enter that value here.  Buy costs are used for reporting margins.
Quantity string   Enter the quantity of the usage record.
Started string   If this record has an start date/time, enter this here.
VendorUserId string   This field maps to the service point billing idenitifer.  This allows you to route the usage to the appropriate billable entity.  For more information about how the billing idenitifers are assigned to service points, see here.



Note: You can create unlimited fields under the COLLECTOR_FIELDS entity. This allows you to collect and map as much data as needed. If you have created extra fields, they will appear in the WSDL XML, but may not be in the above table. When a field is created and mapped you will be able to use this accross the application, for invoice templates, reports, and anywhere else in the application you may need the data. Each field's value will be tied to each record, keeping each piece of data relevant to only the line it was collected from.

Sample Requests
Create

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
         <urn:SessionID>NZEQUFGBWfBvhzNJKTeHFzsaLcHkWnNXpSGBBNyV</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:create xmlns:tns="http://schemas.xmlsoap.org/soap/encoding/" 
                  xmlns="urn:stronglytyped.soap.brmsystems.com" 
		  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <!--Optional:-->
         <urn:brmObjects xsi:type="COLLECTOR_FIELDS">
            <ActivityCollectorId>148</ActivityCollectorId>
            <ActivityDate>2016-09-10 03:30:00</ActivityDate>
            <BillingIdentifier>RTP201610201</BillingIdentifier>
            <Quantity>1</Quantity>
            <GenericUsageIdentifier>RTPA</GenericUsageIdentifier>
         </urn:brmObjects>
      </urn:create>
   </soapenv:Body>
</soapenv:Envelope>


Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Body>
      <urn:createResponse>
         <urn:result>
            <urn:ErrorCode>0</urn:ErrorCode>
            <urn:ErrorText></urn:ErrorText>
            <urn:ErrorElementField></urn:ErrorElementField>
            <urn:Id>15523515</urn:Id>
         </urn:result>
      </urn:createResponse>
   </soapenv:Body>
</soapenv:Envelope> 


Update

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
         <urn:SessionID>NZEQUFGBWfBvhzNJKTeHFzsaLcHkWnNXpSGBBNyV</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <urn:update xmlns="urn:stronglytyped.soap.brmsystems.com">
         <!--Optional:-->
         <urn:brmObjects xsi:type="COLLECTOR_FIELDS">
            <urn:Id>15523515</urn:Id>
            <Quantity>5</Quantity>
         </urn:brmObjects>
      </urn:update>
   </soapenv:Body>
</soapenv:Envelope>


Response 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Body>
      <urn:updateResponse>
         <urn:result>
            <urn:ErrorCode>0</urn:ErrorCode>
            <urn:ErrorText></urn:ErrorText>
            <urn:ErrorElementField></urn:ErrorElementField>
            <urn:Id>15523515</urn:Id>
         </urn:result>
      </urn:updateResponse>
   </soapenv:Body>
</soapenv:Envelope>

Retrieve

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
         <urn:SessionID>NZEQUFGBWfBvhzNJKTeHFzsaLcHkWnNXpSGBBNyV</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                 xmlns:xsd="http://www.w3.org/2001/XMLSchema">
      <urn:retrieve xmlns="urn:stronglytyped.soap.brmsystems.com">
         <urn:queryAnsiSql>Id = 16046067</urn:queryAnsiSql>
         <urn:brmObjectType>COLLECTOR_FIELDS</urn:brmObjectType>
      </urn:retrieve>
   </soapenv:Body>
</soapenv:Envelope>


Response 

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Body>
      <urn:retrieveResponse>
         <urn:result xsi:type="urn:COLLECTOR_FIELDS">
            <urn:Created>2016-10-24T03:07:22.000Z</urn:Created>
            <urn:ActivityCollectorHistoryId>727848</urn:ActivityCollectorHistoryId>
            <urn:ActivityCollectorId>148</urn:ActivityCollectorId>
            <urn:ActivityDate>2016-09-10 03:30:00</urn:ActivityDate>
            <urn:BillingIdentifier>RTP201610201</urn:BillingIdentifier>
            <urn:GenericUsageIdentifier>RTPA</urn:GenericUsageIdentifier>
            <urn:Quantity>1</urn:Quantity>
         </urn:result>
      </urn:retrieveResponse>
   </soapenv:Body>
</soapenv:Envelope>


Upsert

Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
         <urn:SessionID>BnyNwlspyrGrqaxVcjFDszoAUYpdvOMIYpiKqbem</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:upsert>
         <urn:externalIDFieldName>Id</urn:externalIDFieldName>
         <!--Zero or more repetitions:-->
         <urn:brmObjects type="COLLECTOR_FIELDS">
            <ActivityCollectorId>148</ActivityCollectorId>
            <ActivityDate>2016-09-10 03:30:00</ActivityDate>
            <BillingIdentifier>RTP201610201</BillingIdentifier>
            <Quantity>1</Quantity>
            <GenericUsageIdentifier>RTPA</GenericUsageIdentifier>
         </urn:brmObjects>
      </urn:upsert>
   </soapenv:Body>
</soapenv:Envelope>


Response

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Body>
      <urn:upsertResponse>
         <urn:result>
            <urn:created>true</urn:created>
            <urn:ErrorCode>0</urn:ErrorCode>
            <urn:ErrorText></urn:ErrorText>
            <urn:ErrorElementField/>
            <urn:Id>16046067</urn:Id>
         </urn:result>
      </urn:upsertResponse>
   </soapenv:Body>
</soapenv:Envelope>



Checking the UI
Similar to the loading collector data via the UI, the history records generated from the API creates and upserts can be opened in the UI so that the status can be checked. To do so, navigate to Setup > Metered Usage > Usage Collectors. From there, select the appropriate collector profile by clicking on it and then clicking the Collector Activity History child link on the left navigation pane. It will show the load history for this usage collector such as the example below.

From here, the history can be clicked to open the details such as the example below:

On this page, you will see the count of the records processed along with interim status types.

Field Definition
Records in File # of records contained in the loaded file. This includes the header row.
Records Loaded # of records loaded from the file.
Records Invoiced When invoicing is enabled for the collector profile, this shows the number of records from the load file that landed in invoices.
Records Rejected # of records that were rejected. This corresponds to the number of records in the Rejected Records File quicklink. The error messages can be found at the end of each row on this rejected records file.
Records in rating queue Indicates the interim processing status of records. When this is non-zero, it means that there are records in the load file that are queued for rating and eventually will land in invoices.

Key differences on this view compared to UI-loaded usage data are:

  1. File Name will be blank since no file was loaded.
  2. File Size will be Unknown since no file was loaded.
  3. Uploaded File and Rejected Records File will open a blank page since collector data loaded via API are not translated to CSV.
Have more questions? Submit a request

Comments

Powered by Zendesk