SOAP Methods

OVERVIEW

BillingPlatform supports both REST and SOAP integration protocols. This section will cover how to interact with the SOAP web services for retrieving and manipulating records as well as uploading and downloading files. The WSDL will contain all of the standard and custom Entity and field definitions configured in your application at the time its downloaded. Refer to the How To Download The Org's WSDL how-to article for more information on this.

Message bodies for single record manipulation:

Message bodies where needed are written in XML format, such as the example XML request for a CREATE function call against the ACCOUNT entity:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
         <urn:SessionID>zkbLKKfCsGSVmJAFCDndOPghCnhLQNHBPSNrfiGy</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:create>
         <!--Zero or more repetitions:-->
         <urn:brmObjects type="ACCOUNT">
         	<Name>My New Rest Account</Name>
         	<Status>ACTIVE</Status>
         	<AccountType>Required</AccountType>
         </urn:brmObjects>
      </urn:create>
   </soapenv:Body>
</soapenv:Envelope>

Message bodies for multiple records manipulation:

The majority of the BillingPlatform API functions (create, upsert, update, delete, etc.) allow you to manipulate multiple records in one API call, typically by passing multiple records of type brmObject. This is done by passing multiple brmObject collections. For example, if we bulk up the web service call above to create more than one Account record, the following XML request is used:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
         <urn:SessionID>zkbLKKfCsGSVmJAFCDndOPghCnhLQNHBPSNrfiGy</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:create>
         <!--Zero or more repetitions:-->
         <urn:brmObjects type="ACCOUNT">
         	<Name>My New REST Account 01</Name>
         	<Status>ACTIVE</Status>
         	<AccountType>Required</AccountType>
         </urn:brmObjects>
         <urn:brmObjects type="ACCOUNT">
         	<Name>My New REST Account 02</Name>
         	<Status>ACTIVE</Status>
         	<AccountType>Required</AccountType>
         </urn:brmObjects>
         <urn:brmObjects type="ACCOUNT">
         	<Name>My New REST Account 03</Name>
         	<Status>ACTIVE</Status>
         	<AccountType>Required</AccountType>
         </urn:brmObjects>
         <urn:brmObjects type="ACCOUNT">
         	<Name>My New REST Account 04</Name>
         	<Status>ACTIVE</Status>
         	<AccountType>Required</AccountType>
         </urn:brmObjects>
      </urn:create>
   </soapenv:Body>
</soapenv:Envelope>

This will create multiple Account records using only one API function call.

METHODS

LOGIN

BillingPlatform Web Service requests require the client to maintain an ACTIVE session for all interactions with the enterprise billing system APIs. The session is configured to time out after 2 hours of inactivity. The Login method generates the security token or session Id that is used in invoking the subsequent requests.

Sample SOAP, Login Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:login>
         <urn:username>my.username</urn:username>
         <urn:password>xxxxxxxxxxx</urn:password>
      </urn:login>
   </soapenv:Body>
</soapenv:Envelope>

 

Sample SOAP, Login Response:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <urn:loginResponse>
         <urn:result>
            <urn:SessionID>pXzxRAqZyVLMrSAerltkHNHNaSIkIYkjKBEVspNx</urn:SessionID>
            <urn:ErrorCode>0</urn:ErrorCode>
            <urn:ErrorText />
         </urn:result>
      </urn:loginResponse>
   </soapenv:Body>
</soapenv:Envelope>
 

Login code example, c#/java

 

//Instantiate the SOAP Client
bpService.SoapClient svc = new bpService.SoapClient();
           
//authenticate and retrieve the session information in the session header
bpService.SessionHeader header = new bpService.SessionHeader();
            
//execute the login method
bpService.loginResult res = svc.login("my.username"," xxxxxxxxxxx");
            
//add the session Id to the header for all subsequent calls
header.SessionID = res.SessionID;

 

LOGOUT

The call to terminate the active web service session. When invoked, it will invalidate the session Id obtained from the login method

Sample SOAP, Logout Request:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
             <urn:SessionID>sayeiTDshrRKWqVOlqYXFosnChOrWnuXEwFyPucb</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:logout />
   </soapenv:Body>
</soapenv:Envelope>

Sample SOAP, Logout 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:logoutResponse></urn:logoutResponse>
   </soapenv:Body>
</soapenv:Envelope>
 

Logout Request code example, c#/java

 

//Instantiate the SOAP Client
bpService.SoapClient svc = new bpService.SoapClient();
           
//authenticate and retrieve the session information in the session header
bpService.SessionHeader header = new bpService.SessionHeader();
            
//execute the login method
bpService.loginResult res = svc.login("my.username"," xxxxxxxxxxx");
            
//add the session Id to the header for all subsequent calls
header.SessionID = res.SessionID;
 
//
//Simple Logout. This method is void. No response.
// 
svc.logout(header);


CREATE

The Create method is used to add records to your BillingPlatform organization. Each web service call performs object and field level validations on the data submitted within a set of “BrmObject”s before committing the data to the system.
There are certain fields, like the Id, create timestamp, etc. that are automatically populated by the platform and cannot be modified via the API.

Sample SOAP, Create Request (Account):

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <h:SessionHeader xmlns:h="urn:stronglytyped.soap.brmsystems.com"
                       xmlns="urn:stronglytyped.soap.brmsystems.com"
                       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <SessionID>gigkxVXwEzBXtoAAdgbhOzAUCfFApbgMOXxWAUaw</SessionID>
      </h:SessionHeader>
   </s:Header>
   <s:Body xmlns:xsd="http://www.w3.org/2001/XMLSchema"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <create xmlns="urn:stronglytyped.soap.brmsystems.com">
         <brmObjects xsi:type="ACCOUNT">
            <Name>MY FIRST ACCOUNT!</Name>
            <AccountType>ACCOUNT</AccountType>
            <Description>MY TEST ACCOUNT</Description>
            <Status xsi:nil="true">ACTIVE</Status>
         </brmObjects>
      </create>
   </s:Body>
</s:Envelope>

Sample SOAP, Create Response:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                                xmlns:h="urn:stronglytyped.soap.brmsystems.com"
                                xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <h:createResponse>
         <h:result>
            <h:ErrorCode>0</h:ErrorCode>
            <h:ErrorText />
            <h:ErrorElementField />
            <h:Id>25546</h:Id>
         </h:result>
      </h:createResponse>
   </soapenv:Body>
</soapenv:Envelope>
 

Create code example, c#/java

 
//Instantiate the SOAP Client
bpService.SoapClient svc = new bpService.SoapClient();
           
//authenticate and retrieve the session information in the session header
bpService.SessionHeader header = new bpService.SessionHeader();
            
//execute the login method
bpService.loginResult res = svc.login("my.username"," xxxxxxxxxxx");
            
//add the session Id to the header for all subsequent calls
header.SessionID = res.SessionID;
 
//
//Create an empty Account Array for Create
//
bpService.brmObject[] acctList = new bpService.brmObject[1];
            
//Create a new account object
bpService.ACCOUNT acc = new bpService.ACCOUNT();
 
//Set the account attributes
acc.AccountType = "ACCOUNT";
acc.Name = "MY FIRST ACCOUNT!";
acc.Status = "ACTIVE";
acc.Description = "MY FIRST ACCOUNT!";
 
//add the new account to the account list
acctList[0] = acc;
 
//
//Call the create method passing the session header and account list
//
bpService.saveResult[] bpResult = svc.create(header, acctList);
 
//Log out.
svc.logout(header);


UPDATE

The Update method is used to update records within your instance of the enterprise billing system via information submitted within the brmObjects included within the update request. The billing system performs validations on the data submitted within a set of brmObjects before committing changes to the data referenced by the unique “Id” included for each object in the request.

Sample SOAP, Update Request (Account):

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <h:SessionHeader xmlns:h="urn:stronglytyped.soap.brmsystems.com"
                       xmlns="urn:stronglytyped.soap.brmsystems.com"
                       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <SessionID>DmNKJOXlRUawtRLWDowBEDoTuXMANOhJkeSDNQPc</SessionID>
      </h:SessionHeader>
   </s:Header>
   <s:Body xmlns:xsd="http://www.w3.org/2001/XMLSchema"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <update xmlns="urn:stronglytyped.soap.brmsystems.com">
         <brmObjects xsi:type="ACCOUNT">
            <Id>25546</Id>
            <Name>MY FIRST ACCOUNT!</Name>
            <AccountType>ACCOUNT</AccountType>
            <Status>DEACTIVATED</Status>
         </brmObjects>
      </update>
   </s:Body>
</s:Envelope>

Sample SOAP, Update 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:h="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Body>
      <h:updateResponse>
         <h:result>
            <h:ErrorCode>0</h:ErrorCode>
            <h:ErrorText></h:ErrorText>
            <h:ErrorElementField></h:ErrorElementField>
            <h:Id>25546</h:Id>
         </h:result>
      </h:updateResponse>
   </soapenv:Body>
</soapenv:Envelope>
 

An extra key-value combination can be added if certain fields need to be updated to null. In order to do so, the following fieldsToNull value-key needs to be added:

	<brmObjects type="ACCOUNT">
		<fieldsToNull>SomeFieldName1</fieldsToNull>
		<Id>25546</Id>
		...
	</brmObjects>

In case multiple fields need to be updated to null, the key-value combination can be repeated as many times as needed such as the following example

	<brmObjects type="ACCOUNT">
		<fieldsToNull>SomeFieldName1</fieldsToNull>
		<fieldsToNull>SomeFieldName2</fieldsToNull>
		...
		<fieldsToNull>SomeFieldNameX</fieldsToNull>
		<Id>25546</Id>
		...
	</brmObjects>

Update code example, c#/java

 

//Instantiate the SOAP Client
bpService.SoapClient svc = new bpService.SoapClient();
           
//authenticate and retrieve the session information in the session header
bpService.SessionHeader header = new bpService.SessionHeader();
            
//execute the login method
bpService.loginResult res = svc.login("my.username"," xxxxxxxxxxx");
            
//add the session Id to the header for all subsequent calls
header.SessionID = res.SessionID;
 
//
//Create an empty Account Array for Update
//
bpService.brmObject[] acctList = new bpService.brmObject[1];
           
//Create a new account object
bpService.ACCOUNT acc = new bpService.ACCOUNT();
 
//Set the account attributes for update.
//Only need to specify the attributes being updated. 
//The “Id” field is required for Update
acc.Id = "25546";
acc.Name = "MY FIRST ACCOUNT!";
acc.Status = "DEACTIVATED";
 
//add the new account to the account list
acctList[0] = acc;
 
//
//Call the update method passing the session header and account list
//
bpService.saveResult[] bpResult = svc.update(header, acctList);
 
//Log out.
svc.logout(header);


RETRIEVE

This method allows you to retrieve/search for elements in your enterprise billing system. You can specify a query condition or a list of IDs to retrieve an array of brmObjects. The Query element adheres to the ANSI SQL standards. Ex: ”field_name = value” and “or, and” operators. Furthermore, you can leverage the ROWNUM expression to control the number of records that are returned. This is particularly useful for client systems that need to retrieve records in batches instead of processing thousands of records. Refer to Using ROWNUM With RETRIEVE for details:

Sample SOAP, Retrieve Request (Account):

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <h:SessionHeader xmlns:h="urn:stronglytyped.soap.brmsystems.com"
                       xmlns="urn:stronglytyped.soap.brmsystems.com"
                       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <SessionID>DmNKJOXlRUawtRLWDowBEDoTuXMANOhJkeSDNQPc</SessionID>
      </h:SessionHeader>
   </s:Header>
   <s:Body xmlns:xsd="http://www.w3.org/2001/XMLSchema"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <update xmlns="urn:stronglytyped.soap.brmsystems.com">
         <brmObjects xsi:type="ACCOUNT">
            <Id>25546</Id>
            <Name>MY FIRST ACCOUNT!</Name>
            <AccountType>ACCOUNT</AccountType>
            <Status>DEACTIVATED</Status>
         </brmObjects>
      </update>
   </s:Body>
</s:Envelope>

Sample SOAP, Retrieve 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:h="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Body>
      <h:updateResponse>
         <h:result>
            <h:ErrorCode>0</h:ErrorCode>
            <h:ErrorText></h:ErrorText>
            <h:ErrorElementField></h:ErrorElementField>
            <h:Id>25546</h:Id>
         </h:result>
      </h:updateResponse>
   </soapenv:Body>
</soapenv:Envelope>
 

Retrieve Request code example, c#/java

 

//Instantiate the SOAP Client
bpService.SoapClient svc = new bpService.SoapClient();
           
//authenticate and retrieve the session information in the session header
bpService.SessionHeader header = new bpService.SessionHeader();
            
//execute the login method
bpService.loginResult res = svc.login("my.username"," xxxxxxxxxxx");
            
//add the session Id to the header for all subsequent calls
header.SessionID = res.SessionID;
 
//
//Call the Retrieve Method to retrieve a list of Accounts
//Using a “LIKE” Condition for a fuzzy search on the “NAME” field
//
bpService.brmObject[] accResults
   = svc.retrieve(header, "NAME  LIKE 'My First%'", "ACCOUNT", null);
 
//
//Call the Retrieve Method to retrieve a list of Accounts
//Using a list of Ids.
//
String[] accountIdList = new String[2];
accountIdList[0] = “25546”;
accountIdList[0] = “25547”;
bpService.brmObject[] accResults2
   = svc.retrieve(header, null, "ACCOUNT", accountIdList);
 
//Log out.
svc.logout(header);


QUERY

The BP query language offers a powerful tool for retrieving data over both the SOAP and REST APIs as well as the Web tool-kit. All standard and custom objects and their relationships are available in BP SQL.

The BP Query language is structured much like other SQL languages with a couple of exceptions:

  1. Explicit Table or “Entity” joins are not supported
  2. Relationships are referenced via the structured hierarchies constructed in the BP data model
  3. Only one Entity can be referenced in the “From” clause
  4. Use of the asterisk is not supported (ex: “select *”)

For more information please see the section on the BP Query Language.

Sample SOAP, Query Request :

 <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
         <urn:SessionID>hmeMTcxKWavEAnvkpupOOszawLyePdyLbVhlQBsz</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:query>
         <urn:sql>SELECT AccountObj.Name //Parent Relationship
                       , AccountObj.Type
                       , AccountObj.Status
                       , Address1
                       , Address2
                       , City
                       , State
                       , Zip
                       ,(SELECT GrandTotalAmount //Child Relationship/Sub-Query
                              , PaymentAmount
                              , PaymentStatus
                              , ClosedDate
                           FROM Invoice.BillingProfileObj)
                 ,(SELECT Amount  //Nested Child Relationship/Sub-Qu                                           
                       , PaymentDate
                       , PaymentType
                       , BillingProfileObj.AccountObj.Name
                    FROM Payment.BillingProfileObj)
                    FROM Billing_Profile //Driver Entity
                   WHERE AccountObj.Name like 'Blue Moon%' //Where referencing parent field
         </urn:sql>
      </urn:query>
   </soapenv:Body>
</soapenv:Envelope>

Sample SOAP, Query 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:queryResponse
            xmlns:urn="urn:stronglytyped.soap.brmsystems.com"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <urn:result xsi:type="urn:BILLING_PROFILE">
                <urn:Id>40973</urn:Id>
                <urn:Address1>RTP Address1</urn:Address1>
                <urn:Address2></urn:Address2>
                <urn:City>RTP City</urn:City>
                <urn:State>Colorado</urn:State>
                <urn:Zip>80111</urn:Zip>
                <urn:PaymentBillingProfileObj>
                    <urn:Id>449553</urn:Id>
                    <urn:Amount>0</urn:Amount>
                    <urn:PaymentDate>2015-05-15T09:33:06.241000-06:00</urn:PaymentDate>
                    <urn:PaymentType>CREDIT CARD</urn:PaymentType>
                    <urn:BillingProfileObj>
                        <urn:Id>40973</urn:Id>
                        <urn:AccountObj>
                            <urn:Id>10205</urn:Id>
                            <urn:Name>Blue Moon -- ATT</urn:Name>
                        </urn:AccountObj>
                    </urn:BillingProfileObj>
                </urn:PaymentBillingProfileObj>
                <urn:InvoiceBillingProfileObj>
                    <urn:Id>414106</urn:Id>
                    <urn:GrandTotalAmount>101</urn:GrandTotalAmount>
                    <urn:PaymentAmount>0</urn:PaymentAmount>
                    <urn:PaymentStatus>NOT PAID</urn:PaymentStatus>
                    <urn:ClosedDate></urn:ClosedDate>
                </urn:InvoiceBillingProfileObj>
                <urn:AccountObj>
                    <urn:Id>10205</urn:Id>
                    <urn:Name>Blue Moon -- ATT</urn:Name>
                    <urn:Type>Partner Retail</urn:Type>
                    <urn:Status>ACTIVE</urn:Status>
                </urn:AccountObj>
            </urn:result>
        </urn:queryResponse>
    </soapenv:Body>
</soapenv:Envelope>
 


DELETE

The delete operation accepts an object type and ID and is used to purge records from the billing system.

Sample SOAP, Delete Request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
           <urn:SessionID>DmNKJOXlRUawtRLWDowBEDoTuXMANOhJkeSDNQPc</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:delete>
         <urn:brmObjectType>ACCOUNT</urn:brmObjectType>
         <!--Zero or more repetitions:-->
         <urn:Id>27316</urn:Id>
      </urn:delete>
   </soapenv:Body>
</soapenv:Envelope>

Sample SOAP, Delete Response:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:urn="urn:stronglytyped.soap.brmsystems.com"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <urn:deleteResponse>
         <urn:result>
            <urn:ErrorCode>0</urn:ErrorCode>
            <urn:ErrorText />
            <urn:Id>27316</urn:Id>
            <urn:Success>true</urn:Success>
         </urn:result>
      </urn:deleteResponse>
   </soapenv:Body>
</soapenv:Envelope>

 

Delete code example, c#/java

 

//Instantiate the SOAP Client
bpService.SoapClient svc = new bpService.SoapClient();
           
//authenticate and retrieve the session information in the session header
bpService.SessionHeader header = new bpService.SessionHeader();
            
//execute the login method
bpService.loginResult res = svc.login("my.username"," xxxxxxxxxxx");
            
//add the session Id to the header for all subsequent calls
header.SessionID = res.SessionID;
 
//
//Call the Delete Method to delete one or more Accounts
//
String[] accountIdList = new String[1];
accountIdList[0] = "25546";
 
bpService.DeleteResult[] delRes
      = svc.delete(header, "ACCOUNT", accountIdList);
 
//Log out.
svc.logout(header);


UNDELETE

The undelete operation accepts an object type and ID and is used to restore records that have been deleted from the recycle bin. The results are subject to the availability of the requested Objects in the recycle bin and subject to recycle bin configuration.

Sample SOAP, Undelete Request:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"   
                  xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
         <urn:SessionID>DmNKJOXlRUawtRLWDowBEDoTuXMANOhJkeSDNQPc</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:undelete>
         <urn:brmObjectType>ACCOUNT</urn:brmObjectType>
         <!--Zero or more repetitions:-->
         <urn:Id>27316</urn:Id>
      </urn:undelete>
   </soapenv:Body>
</soapenv:Envelope>

Sample SOAP, Undelete Response:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:urn="urn:stronglytyped.soap.brmsystems.com"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <urn:undeleteResponse>
         <urn:result>
            <urn:ErrorCode>0</urn:ErrorCode>
            <urn:ErrorText />
            <urn:Id>27316</urn:Id>
            <urn:Success>true</urn:Success>
         </urn:result>
      </urn:undeleteResponse>
   </soapenv:Body>
</soapenv:Envelope>

 

Undelete Request code example, c#/java

 

//Instantiate the SOAP Client
bpService.SoapClient svc = new bpService.SoapClient();
           
//authenticate and retrieve the session information in the session header
bpService.SessionHeader header = new bpService.SessionHeader();
            
//execute the login method
bpService.loginResult res = svc.login("my.username"," xxxxxxxxxxx");
            
//add the session Id to the header for all subsequent calls
header.SessionID = res.SessionID;
 
//
//Call the Undelete Method to restore one or more records
//from the recycle bin
//
String[] accountIdList = new String[1];
accountIdList[0] = "25546";
 
bpService.UndeleteResult [] undelRes
      = svc.undelete(header, "ACCOUNT", accountIdList);
 
//Log out.
svc.logout(header);

UPSERT

The Upsert method allows you to specify a key field in the data used to determine whether to insert or update the records passed in over the API. If the value of the Key exists in the billing system, the record will be updated. If not, the record is inserted. Only fields that have marked as an “External Key” or the Id field can be used in an upsert operation.

Sample SOAP, Upsert Request (Account):

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <h:SessionHeader xmlns:h="urn:stronglytyped.soap.brmsystems.com"
                       xmlns="urn:stronglytyped.soap.brmsystems.com"
                       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <SessionID>ypcQforXhcjwYgxvVzOzHztUMJmDSPhFwhCedNDx</SessionID>
      </h:SessionHeader>
   </s:Header>
   <s:Body xmlns:xsd="http://www.w3.org/2001/XMLSchema"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <upsert xmlns="urn:stronglytyped.soap.brmsystems.com">
         <externalIDFieldName>Name</externalIDFieldName>
         <brmObjects xsi:type="ACCOUNT">
            <Id xsi:nil="true" />
            <Name>MY FIRST ACCOUNT!</Name>
            <AccountType>ACCOUNT</AccountType>
            <Status>ACTIVE</Status>
         </brmObjects>
      </upsert>
   </s:Body>
</s:Envelope>

Sample SOAP, Update Response:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:h="urn:stronglytyped.soap.brmsystems.com"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <h:upsertResponse>
         <h:result>
            <h:created>false</h:created>
            <h:ErrorCode>0</h:ErrorCode>
            <h:ErrorText />
            <h:ErrorElementField />
            <h:Id>25538</h:Id>
         </h:result>
      </h:upsertResponse>
   </soapenv:Body>
</soapenv:Envelope>

An extra key-value combination can be added if certain fields need to be updated to null. In order to do so, the following fieldsToNull value-key needs to be added:

	<externalIDFieldName>Name</externalIDFieldName>
	<brmObjects type="ACCOUNT">
		<fieldsToNull>SomeFieldName1</fieldsToNull>
		<Name>MyName</Name>
		...
	</brmObjects>

In case multiple fields need to be updated to null, the key-value combination can be repeated as many times as needed such as the following example

	<externalIDFieldName>Name</externalIDFieldName>
	<brmObjects type="ACCOUNT">
		<fieldsToNull>SomeFieldName1</fieldsToNull>
		<fieldsToNull>SomeFieldName2</fieldsToNull>
		...
		<fieldsToNull>SomeFieldNameX</fieldsToNull>
		<Name>MyName</Name>
		...
	</brmObjects>

Upsert code example, c#/java

 

//Instantiate the SOAP Client
bpService.SoapClient svc = new bpService.SoapClient();
           
//authenticate and retrieve the session information in the session header
bpService.SessionHeader header = new bpService.SessionHeader();
            
//execute the login method
bpService.loginResult res = svc.login("my.username"," xxxxxxxxxxx");
            
//add the session Id to the header for all subsequent calls
header.SessionID = res.SessionID;
 
//
//Create an empty Account Array for Upsert
//
bpService.brmObject[] acctList = new bpService.brmObject[1];
           
//Create a new account object
bpService.ACCOUNT acc = new bpService.ACCOUNT();
 
//Set the account attributes for upsert.
acc.Name = "MY FIRST ACCOUNT!";
acc.Status = " ACTIVE";
 
//add the new account to the account list
acctList[0] = acc;
 
//
//Call the upsert method passing the session header, upsert field name,
//and the account list
//
bpService.UpsertResult[] upsertResponse
    = svc.upsert(header, "Name", acctList);
 
//Log out.
svc.logout(header);

FILEUPLOAD

BillingPlatform allows you to upload files to entities.  You may use the file upload method to upload files that have been Base64 encoded to a field on any object of type “FILE”.

Sample SOAP, File Uplaod Request (Account):

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
<urn:SessionID>DmNKJOXlRUawtRLWDowBEDoTuXMANOhJkeSDNQPc</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:fileUpload>
         <urn:EntityName>ACCOUNT</urn:EntityName>
         <urn:FieldName>Document</urn:FieldName>
         <urn:Id>10201</urn:Id>
         <urn:FileName>Document</urn:FileName>
         <urn:Data>dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
         cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
         cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
         IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
         c3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3Qg
         dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
         cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
         cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
         IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
         c3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3Qg
         dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
         cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
         cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
         IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
         c3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3Qg
         dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
         cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
         cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
         IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
         c3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3Qg
         dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
         cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
         cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
         IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
         c3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3Qg
         dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
         cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
         cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
         IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
         c3Qg</urn:Data>
      </urn:fileUpload>
   </soapenv:Body>
</soapenv:Envelope>

Sample SOAP, File Uplaod Response:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:urn="urn:stronglytyped.soap.brmsystems.com"
                  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <urn:fileUploadResponse>
         <urn:result>
            <urn:ErrorCode>0</urn:ErrorCode>
            <urn:ErrorText />
            <urn:ErrorElementField />
            <urn:Id>421</urn:Id>
         </urn:result>
      </urn:fileUploadResponse>
   </soapenv:Body>
</soapenv:Envelope>
 
 
fileUpload code example using c#

 

//Global file variables
int DefaultSize = 1024000;
int BufferSize = DefaultSize;
int CharsToRead = DefaultSize / 2;
FileStream fs = null;
StreamWriter sw = null;
FileStream fsOut = null;
int bytesRead = 0;
int totalBytesRead = 0;
byte[] bytes = new byte[BufferSize];
 
//Instantiate the SOAP Client
bpService.SoapClient svc = new bpService.SoapClient();
           
//authenticate and retrieve the session information in the session header
bpService.SessionHeader header = new bpService.SessionHeader();
            
//execute the login method
bpService.loginResult res = svc.login("my.username"," xxxxxxxxxxx");
            
//add the session Id to the header for all subsequent calls
header.SessionID = res.SessionID;
 
 
//Open srcFile in read-only mode.
try
{
   string srcFile = "C:\\BRM Business\\AnualReport2009.pdf";
   fs = new FileStream(srcFile, FileMode.Open,
                       FileAccess.Read, FileShare.Read, BufferSize);
   long sourceSize = new FileInfo(srcFile).Length;
 
   if (sourceSize <= BufferSize)
   {
      //Open stream writer
      bytesRead = fs.Read(bytes, 0, BufferSize);
 
      if (bytesRead > 0)
      {
         //Convert the file to base 64
         string base64String
           = Convert.ToBase64String(bytes, 0, bytesRead);
         totalBytesRead += bytesRead;
                      
         //convert the base 64 string to a byte array
         byte[] base64bytes
              = new byte[base64String.Length * sizeof(char)];
                                     
         System.Buffer.BlockCopy(base64String.ToCharArray(),
                                 0, bytes, 0, base64bytes.Length);
 
         //upload the file using the SOAP web service
         bpService.saveResult[] fileUpRes
            = svc.fileUpload(header, "ACCOUNT", "Document", "10201",
                              "annualReport.pdf", bytes);
      }
   }
}
catch (IOException)
{
   return;
}
//Log out.
svc.logout(header);

FILEDOWNLOAD

You can download files using the file download method.  Files downloaded will be Base64 encoded and you must use a Base64 decoder in order to convert the downloaded file.

Sample SOAP, File Download Request (Account):

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com">
   <soapenv:Header>
      <urn:SessionHeader>
         <urn:SessionID>DmNKJOXlRUawtRLWDowBEDoTuXMANOhJkeSDNQPc</urn:SessionID>
      </urn:SessionHeader>
   </soapenv:Header>
   <soapenv:Body>
      <urn:file_download>
         <urn:EntityName>ACCOUNT</urn:EntityName>
         <urn:FieldName>Document</urn:FieldName>
         <urn:Id>10201</urn:Id>
      </urn:file_download>
   </soapenv:Body>
</soapenv:Envelope>

Sample SOAP, File Download Response:

<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:stronglytyped.soap.brmsystems.com" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <soapenv:Body>
      <urn:file_downloadResponse>
         <urn:downloadResult>
            <urn:ErrorCode>0</urn:ErrorCode>
            <urn:ErrorText />
            <urn:ErrorElementField />
            <urn:Data>dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
            cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
            cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
            IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
            c3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3Qg
            dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
            cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
            cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
            IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
            c3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3Qg
            dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
            cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
            cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
            IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
            c3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3Qg
            dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
            cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
            cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
            IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
            c3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3Qg
            dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
            cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
            cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
            IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
            c3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3Qg
            dGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhp
            cyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBp
            cyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBh
            IHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRlc3QgdGhpcyBpcyBhIHRl
            c3Qg</urn:Data>
         </urn:downloadResult>
      </urn:file_downloadResponse>
   </soapenv:Body>
</soapenv:Envelope>
 

FileDownload code example using c#

//Instantiate the SOAP Client
bpService.SoapClient svc = new bpService.SoapClient();
           
//authenticate and retrieve the session information in the session header
bpService.SessionHeader header = new bpService.SessionHeader();
            
//execute the login method
bpService.loginResult res = svc.login("my.username"," xxxxxxxxxxx");
            
//add the session Id to the header for all subsequent calls
header.SessionID = res.SessionID;
 
//create a file stream Object to hold the file content from the service
FileStream fs
     = new FileStream("doc.txt", FileMode.Create, FileAccess.Write);
 
//retrieve a document from a field on an Account
//with Id 10201 from a field called "Document"
bpService.downloadResult[] fileDownRes
     = svc.file_downloadResponse(header, "ACCOUNT", "Document", "10201");
           
//convert the base 64 char array to a byte array
byte[] bytes
        = Convert.FromBase64String(fileDownRes[0].Data.ToString());
          
//write the file to the file system
fs.Write(bytes, 0, bytes.Length);
 
 
//Log out.
svc.logout(header);

RELATIONSHIPS and “Obj”

BillingPlatform provides the ability to model your business data by building relationships between Entities. This is done via the Lookup field types where a Lookup field defined on one Entity (the child) references a Parent record on the associated, Parent Entity. When these lookup fields are created, the system will create a corresponding, relationship Object which will manifest in the API with the same name as the field with the word “Obj” appended to it.

For example, the relationship from the BILLING_PROFILE entity to the ACCOUNT Entity uses a field called “AccountId”. The corresponding relationship object is called AccountObj. The Relationship objects can be leveraged to build the parent Child relationships when inserting child records without having to know the Id of the Parent Object. This can be done by including the Parent’s External Key inside the relationship object when creating the child object as follows:

<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
   <s:Header>
      <h:SessionHeader xmlns:h="urn:stronglytyped.soap.brmsystems.com"
                       xmlns="urn:stronglytyped.soap.brmsystems.com"
                       xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <SessionID>OKBQUxWSvFZsJbvwiOyZLgKLEkQRqyqPUPrAUgWp</SessionID>
      </h:SessionHeader>
   </s:Header>
   <s:Body xmlns:xsd="http://www.w3.org/2001/XMLSchema"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <create xmlns="urn:stronglytyped.soap.brmsystems.com">
         <brmObjects xsi:type="BILLING_PROFILE">
            <Id xsi:nil="true" />
            <CreatedUserObj xsi:nil="true" />
            <UpdatedUserObj xsi:nil="true" />
            <AccountBalance xsi:nil="true" />
            <AccountId xsi:nil="true" />
            <!--The Account Object included here will Translate the natural
                External key –“Name” to an Account Id formint the relationship
                to the Billing_Profile
            -->
            <AccountObj>
               <Id xsi:nil="true" />
               <Name>AQUA7</Name>
            </AccountObj>
            <Address1>1234 Fith Street</Address1>
            <Address2 xsi:nil="true" />
            <BillTo>Yogi Bear</BillTo>
            <BillingCycle>MONTHLY</BillingCycle>
            <BillingMethod>MAIL</BillingMethod>
            <City>Denver</City>
            <Country>US</Country>
             … … …
         </brmObjects>
      </create>
   </s:Body>
</s:Envelope>
 

The Above, SOAP excerpt shows a BILLING_PROFILE insert request naming the parent account by leveraging the AccountObj relationship. Below is as sample of the same method using C#:

           //Create an List of BP Account Objects for Upsert  
           bpService.brmObject[] acctList = new bpService.brmObject[1];
           
           bpService.ACCOUNT acc = new bpService.ACCOUNT();
           acc.AccountType = "ACCOUNT";
           acc.Name = "AQUA7";
           acc.Status = "ACTIVE";
           acctList[0] = acc;
 
            //upsert the accounts leveraging the “Name” field, a natural External Key for this Entity
            bpService.UpsertResult[] upsertResponse = svc.upsert(header, "Name", acctList);
 
            //Create a list of Billing Profile Objects to relate to the account
            bpService.brmObject[] bpList = new bpService.brmObject[upsertResponse.Length];
           
            bpService.BILLING_PROFILE bp = new bpService.BILLING_PROFILE();
            //Add the Account to the request to build the relationship
            bp.AccountObj = acc;
            bp.Address1 = "This is a test Street Unit" ;
            bp.BillingCycle = "MONTHLY";
            bp.BillingMethod = "MAIL";
            bp.BillTo = "Yogi Bear";
            bp.City = "Denver";
            bp.Country = "US";
            bp.Email = "yogi.bear@billingplatform.com";
            bp.InvoiceTemplateId = "108";
            bp.MonthlyBillingDate = "31";
            bp.PaymentTermDays = 30;
            bp.PaymentTermDaysSpecified = true;
            bp.TimeZoneId = "346";
            bp.CurrencyCode = "USD";
            bp.InvGraceDaysBeforeClosing = 0;
            bp.InvGraceDaysBeforeClosingSpecified = true;
            bp.ManualCloseFlag = "0";
            bp.InvoiceApprovalFlag = "0";
            bp.StatementApprovalFlag = "0";
            bpList[0] = bp;
 
            //make the call to create the billing profiles
            bpService.saveResult[] bpResult = svc.create(header, bpList);                            
 

PUTTING IT ALL TOGETHER

Now that we have an understanding of the API methods and a general sense of how they apply to the few objects listed previously, lets put this knowledge to use in a more practical and comprehensive setting. In the next section we will look at how to leverage the SOAP API to do the following:

  1. Create an Account
  2. Add a billing Profile to the Account
  3. Add an Account Contract
  4. Add a Contract Rate
  5. Add an Account Product
  6. Add an Account Package
  7. Retrieve an Account Product
  8. Update the Rate On the Account Product
  9. Retrieve a Contract Rate
  10. Delete a Contract Rate

We will use C# in this example which is similar to Java in syntax.

static void Main(string[] args)
        {
     /***************************************************************************************/
     //
     // Authenticate and retrieve a session Id for use in the subsequent transactions
     //
 
     bpService.SoapClient svc = new bpService.SoapClient();
     bpService.SessionHeader header = new bpService.SessionHeader();
     bpService.loginResult res = new bpService.loginResult();
 
     res = svc.login("btest", "brm2");
 
     header.SessionID = res.SessionID;
 
     /***************************************************************************************/
     //
     //     1. Create The Account and Billing Profile.
     //
 
     //Create aList of BP Account Objects for Upsert  
     bpService.brmObject[] acctList = new bpService.brmObject[1];
 
     bpService.ACCOUNT account_rec = new bpService.ACCOUNT();
 
     account_rec.AccountType = "ACCOUNT";
     account_rec.Name = "AQUA11";
     account_rec.Status = "ACTIVE";
 
     acctList[0] = account_rec;
 
     //upsert the accounts leveraging the “Name” field, a natural External Key
     // for this Entity
 
     bpService.UpsertResult[] acctResponse = svc.upsert(header, "Name", acctList);
 
     account_rec.Id = acctResponse[0].Id;
 
 
     /***************************************************************************************/
     //
     //    2. Create the Billing Profile
     //
 
     //retrieve the invoice template
     bpService.brmObject[] bo = svc.retrieve(header, "default_flag = '1'", "INVOICE_TEMPLATE", null);
 
     bpService.INVOICE_TEMPLATE invTemplate = (bpService.INVOICE_TEMPLATE)bo[0];
 
     //retrieve the time zone
     bo = svc.retrieve(header, "tzName = 'US/Mountain'", "TIME_ZONE", null);
     bpService.TIME_ZONE timeZone = (bpService.TIME_ZONE)bo[0];
 
     //retrieve the currency codes for use in creating or updating the billing profile
     bo = svc.retrieve(header, "currency_code = 'USD' ", "CURRENCY", null)
 
     bpService.CURRENCY curr = (bpService.CURRENCY)bo[0];
 
     bpService.BILLING_PROFILE bp = new bpService.BILLING_PROFILE();
 
     bp.AccountId = account_rec.Id;
     //bp.AccountObj = account_rec;
     bp.Address1 = "Test WS 1";
     bp.Attention = "TEST";
     bp.BillTo = "TEST";
     bp.BillingCycle = "MONTHLY";
 
     bp.BillingMethod = "MAIL";
     bp.CurrencyCodeObj = curr;
     bp.City = "Denver";
     bp.State = "CO";
     bp.Country = "USA";
     bp.Zip = "111111";    //Postal Code      
     bp.Email = "test.recipientn2@billingplatform.com";
     bp.Fax = "1112223344";
     bp.InvoiceDeliveryMethod = "EMAIL";
     bp.InvoiceTemplateId = invTemplate.Id;
     //bp.InvoiceTemplateObj = invTemplate;
     bp.ManualCloseFlag = "1";    //1 = true; 0 = false
     //bp.ManualCloseFlagSpecified = true;
     bp.MonthlyBillingDate = "31";    //Day the invoice closes Monthly. 31 indicates Last day of month
     //bp.MonthlyBillingDateSpecified = true;
     bp.PaymentTermDays = 30;    //Net Terms. Drives aging and Dunning
     bp.PaymentTermDaysSpecified = true;
     bp.Phone = "1112224455";
     bp.Status = "ACTIVE";
     //bp.TimeZoneObj = timeZone;
     bp.TimeZoneId = timeZone.Id;
     bp.InvGraceDaysBeforeClosing = 0;    //number of days past the closing day to leave the invoice open
     bp.InvGraceDaysBeforeClosingSpecified = true;
 
     //check for the existence of the billing profile for this account
     bo = svc.retrieve(header, "ACCOUNT.Name = '" + account_rec.Name + "'", "BILLING_PROFILE", null);
 
     if (bo.Length > 0)
     {
         bp.Id = bo[0].Id;
     }
 
     bpService.brmObject[] bpList = new bpService.brmObject[1];
 
     bpList[0] = bp;
 
     bpService.UpsertResult[] bpResult = svc.upsert(header, "Id", bpList);  //Upsert based on primary key/Id
 
     /***************************************************************************************/
     //
     //    3. Create a Contract
     //
 
     //Create a Contract
     bpService.brmObject[] contracts = new bpService.brmObject[1];
 
     bpService.CONTRACT contract_rec = new bpService.CONTRACT();
     contract_rec.AccountId = account_rec.Id;
     contract_rec.ContractNumber = "123456-abcdefg0";
     contract_rec.ContractStatus = "ACTIVE";
     contract_rec.StartDate = DateTime.Now;
     contract_rec.StartDateSpecified = true;
     contract_rec.OnEndDate = "Renew";
 
 
     //add the contract to the contract list since the API is structured for bulk
     contracts[0] = contract_rec;
 
     //Create the Contract record
     bpService.saveResult[] contractResults = svc.create(header, contracts);
 
     contract_rec.Id = contractResults[0].Id;
 
 
 
     /***************************************************************************************/
     //
     //    4 (a) Create a Contract Rate
     //
 
     //retrieve the Product for which to specify a rate
     bpService.brmObject[] producRetrievetResults = svc.retrieve(header
         , "Name = 'test subcription' and RatingMethodId is not null"
         , "PRODUCT", null);//last parameter is a list of Ids. Specify null.
 
     //convert the generic, brmObjects to an array of PRODUCT objects
     bpService.PRODUCT[] products = Array.ConvertAll(producRetrievetResults, 
         item => (bpService.PRODUCT)item);
 
     //create Rate ad Pricing objects. These two are dependent and will comprise the contract rate
     bpService.CONTRACT_RATE contract_rate_rec = new bpService.CONTRACT_RATE();
 
     contract_rate_rec.ContractId = contract_rec.Id;
     //contract_rate_rec.ContractObj = contract_rec;
     contract_rate_rec.EndDate = null;
     contract_rate_rec.ProductId = products[0].Id;
     contract_rate_rec.StartDate = DateTime.Now;
     contract_rate_rec.StartDateSpecified = true;
     contract_rate_rec.ExternalId = "12354" + contracts[0].Id; //ensure uniqueness (example only)
 
 
 
     bpService.brmObject[] rates = new bpService.brmObject[1];
 
     rates[0] = contract_rate_rec;
 
     bpService.UpsertResult[] ppResults = svc.upsert(header, "ExternalId", rates);
 
     contract_rate_rec.Id = ppResults[0].Id;
 
 
     /***************************************************************************************/
     //
     //    4 (b) Create a Pricing record
     //
 
     bpService.PRICING pricing_rec = new bpService.PRICING();
     bpService.brmObject[] pricing = new bpService.brmObject[1];
 
 
 
     //Add the contract rate object for upsert of the Pricing record.
     //The Contract_Rate has an external key specified.
     // This will eliminate the need to retrieve the contract rate record’s Id. 
 
     pricing_rec.ContractRateId = contract_rate_rec.Id;
     //pricing_rec.ContractRateObj = contract_rate_rec;
     pricing_rec.Rate = 100000;//WOW! That’s expensive…
     pricing_rec.RateSpecified = true;
     pricing_rec.CurrencyCode = "USD";
 
     //add the pricing record to the array for upsert      
     pricing[0] = pricing_rec;
 
     //upsert the pricing records
     bpService.UpsertResult[] oResults = svc.upsert(header, "Id", pricing);
 
     /***************************************************************************************/
     //
     //    5. Add an Account Products
     //
 
     bpService.ACCOUNT_PRODUCT[] acctProdcuts = new bpService.ACCOUNT_PRODUCT[1];
 
     bpService.ACCOUNT_PRODUCT acc_product_rec = new bpService.ACCOUNT_PRODUCT();
 
     acc_product_rec.AccountId = account_rec.Id;
     acc_product_rec.ContractId = contract_rec.Id;
     acc_product_rec.CreatedSpecified = true;
     acc_product_rec.ProductId = products[0].Id;
     acc_product_rec.Quantity = 1;
     acc_product_rec.QuantitySpecified = true;
     acc_product_rec.StartDate = DateTime.Now;
     acc_product_rec.StartDateSpecified = true;
 
     //add the account Product to the array for creation
     acctProdcuts[0] = acc_product_rec;
 
     //create the account product instance
     bpService.saveResult[] apResults = svc.create(header, acctProdcuts);
 
     //add pricing to the account product
     bpService.PRICING pricing_rec3 = new bpService.PRICING();
     pricing_rec3.Rate = 2000;
     pricing_rec3.RateSpecified = true;
     pricing_rec3.AccountProductId = apResults[0].Id;
 
     bpService.brmObject[] pricing2 = new bpService.brmObject[1];
     pricing2[0] = pricing_rec3;
 
     //create the pricing record
     bpService.saveResult[] apPricingResults = svc.create(header, pricing2);
 
 
     /***************************************************************************************/
     //
     //    6. Create Account Packages
     //
 
     //retrieve the package of interest
     bpService.brmObject[] packageRetrieveResults = svc.retrieve(header, 
         "Name like 'Online Service%'", "PACKAGE", null);
 
     //create an array of Account Packages for insert
     bpService.ACCOUNT_PACKAGE[] acctPackages = new bpService.ACCOUNT_PACKAGE[1];
 
     //create the account package instance
     bpService.ACCOUNT_PACKAGE acctPackage_rec = new bpService.ACCOUNT_PACKAGE();
 
     acctPackage_rec.PackageId = packageRetrieveResults[0].Id;
     acctPackage_rec.AccountId = account_rec.Id;
     acctPackage_rec.ContractId = contract_rec.Id;
     acctPackage_rec.StartDate = DateTime.Now;
     acctPackage_rec.StartDateSpecified = true;
 
     //add the package object to the array
     acctPackages[0] = acctPackage_rec;
 
     //create the package
     bpService.saveResult[] acctPackagesResults = svc.create(header, acctPackages);
 
     /***************************************************************************************/
     //
     // 7.      Retrieve an Account Product
     //
 
     //get the package Items generated by the new account package creation
     bpService.brmObject[] packageProductResults = svc.retrieve(header
      , "AccountPackageId = '" + acctPackagesResults[0].Id + "'"
      , "ACCOUNT_PRODUCT",
      null);
 
     /***************************************************************************************/
     //
     //  8.     Update the start and end dates on the Account Product
     //
 
     //Create a list of account Products to update
     bpService.ACCOUNT_PRODUCT[] updPackageProducts
        = new  bpService.ACCOUNT_PRODUCT[packageProductResults.Length];
 
     //iterate through the account package products and update the necessary values
     for (int i = 0; i < packageProductResults.Length; i++)
     {
         acc_product_rec = (bpService.ACCOUNT_PRODUCT)packageProductResults[i];
 
         //update the term dates on the package product
         acc_product_rec.StartDate = ((DateTime)acc_product_rec.StartDate).AddMonths(1);
         acc_product_rec.EndDate = ((DateTime)acc_product_rec.StartDate).AddYears(1);
         acc_product_rec.EndDateSpecified = true;
         updPackageProducts[i] = acc_product_rec;
     }
 
     //update the package products
     bpService.saveResult[] acctPackageProdsResults = svc.update(header, updPackageProducts);
 
     //Log Out
     svc.logout(header);
 
 
 }//static void Main
 
 

Related Topics

Have more questions? Submit a request

Comments

Powered by Zendesk