InsertFacadeObject
|
Initial Build |
2006.02 |
|
xWEB |
Web Method |
|
Response Type |
String |
This method inserts a netFORUM Facade Object and if successful returns the primary key of the Facade object record that was created.
Parameters
- szObjectName (string). The name of the Object you want to insert. See XWeb:GetFacadeObjectList for more direction on this parameter.
- oNode (XmlNode). An XmlNode containing elements for each column you want to pass a value.
The <oNode> XmlNode must be patterned in the following way, assuming the namespace is called ns. You could copy-and-paste this pattern below and use it as a starting point:
<ns:InsertFacadeObject xmlns:ns="http://www.avectra.com/2005/">
<ns:szObjectName>NameOfObjectGoesHere</ns:szObjectName>
<ns:oNode>
<ns:NameOfObjectGoesHereObjects>
<ns:NameOfObjectGoesHereObject>
<ns:zzz_field1>Some Value Goes Here</ns:zzz_field1>
<ns:zzz_field2>a6e3cb3f-c1cd-4ada-b961-e747db2326f3</ns:zzz_field2>
<ns:qqq_field3>01/12/2008</ns:qqq_field3>
</ns:NameOfObjectGoesHereObject>
</ns:NameOfObjectGoesHereObjects>
</ns:oNode>
</ns:InsertFacadeObject>
Let's take a look at each line:
<!-- Name of the object followed by plural "Objects", eg "IndividualObjects" -->
<ns:NameOfObjectGoesHereObjects>...
</ns:NameOfObjectGoesHereObjects>
This line above has the value of the object in the szObjectName parameter followed with word Objects in plural. For example, <ns:IndividualObjects> or <ns:ABCBusinessCodeObjects>.
Within this <ns:ZZZZZZZObjects> node, starting on the next line down, will be at least one (and potentially multiple) nodes of one object each, as shown below. Each node is named identically as above except the end of the node name is the singular Object. Following from the example above, you might have <ns:IndividualObject> or <ns:ABCBusinessCodeObject>. Example:
<!-- Name of the object followed by singular "Object", eg "IndividualObject" -->
<ns:NameOfObjectGoesHereObject>...
</ns:NameOfObjectGoesHereObject>
Finally, within the singular Object node, you will have as many elements as you need to pass, one element for each field, as shown in the middle lines in the example above:
<ns:zzz_field1>
Some Value Goes Here</ns:zzz_field1><ns:zzz_field2>a6e3cb3f-c1cd-4ada-b961-e747db2326f3</ns:zzz_field2><ns:qqq_field3>01/12/2008</ns:qqq_field3>
Note: technically, netFORUM does not care how you name the <Objects> and <Object> node, as long as the request has an outer node and one or more inner nodes. We use the <ZZZObjects> and <ZZZObject> naming convention because the response will name the nodes in this manner, and because it helps us understand the general structure.
Even this strange looking request will work:
<ns:InsertFacadeObject>
<ns:szObjectName>co_prefix</ns:szObjectName>
<ns:oNode>
<ns:Hello>
<ns:dog>
<ns:prf_code>Mr.</ns:prf_code>
</ns:dog>
<ns:cat>
<ns:prf_code>Mrs.</ns:prf_code>
</ns:cat>
</ns:Hello>
</ns:oNode>
</ns:InsertFacadeObject>
The response will be:
<InsertFacadeObjectResponse xmlns="http://www.avectra.com/2005/">
<InsertFacadeObjectResult>
<co_prefixObjects recordReturn="2" xsi:schemaLocation="http://www.avectra.com/2005/ co_prefix.xsd">
<co_prefixObject>
<prf_key>dab48d25-3de5-4d7a-b818-a890620207a9</prf_key>
</co_prefixObject>
<co_prefixObject>
<prf_key>3ef3fb53-c66a-464e-af28-c4e73fd6a63d</prf_key>
</co_prefixObject>
</co_prefixObjects>
</InsertFacadeObjectResult>
</InsertFacadeObjectResponse>
Response
Primary Key of the newly created object, as a string.
Sample Request For One Object
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Header>
<m:AuthorizationToken xmlns:m="http://www.avectra.com/2005/">
<m:Token>72786a3e-d227-4772-bb30-8037ba6b7b26</m:Token>
</m:AuthorizationToken>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<m:InsertFacadeObject xmlns:m="http://www.avectra.com/2005/">
<m:szObjectName>IndividualEmail</m:szObjectName>
<m:oNode>
<m:IndividualEmailObjects>
<m:IndividualEmailObject>
<m:eml_address>jroos200@insp.com</m:eml_address>
<m:eml_cst_key>a6e3cb3f-c1cd-4ada-b961-e747db2326f3</m:eml_cst_key>
</m:IndividualEmailObject>
</m:IndividualEmailObjects>
</m:oNode>
</m:InsertFacadeObject>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Sample Response For One Object
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>fdd614ae-f419-4544-b165-2d6476b0c312</Token>
</AuthorizationToken>
<wsa:Action>http://www.avectra.com/2005/InsertFacadeObjectResponse</wsa:Action>
<wsa:MessageID>uuid:84e264fd-b7fa-4ffe-9b63-51dc121fb334</wsa:MessageID>
<wsa:RelatesTo>uuid:8e050528-cd36-40eb-845c-8eb5c68e9dbf</wsa:RelatesTo>
<wsa:To>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:To>
<wsse:Security>
<wsu:Timestamp wsu:Id="Timestamp-e4e89e0a-81b9-4ec7-9700-09b62e1a69ba">
<wsu:Created>2006-09-22T12:43:38Z</wsu:Created>
<wsu:Expires>2006-09-22T12:48:38Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soap:Header>
<soap:Body>
<InsertFacadeObjectResponse xmlns="http://www.avectra.com/2005/">
<InsertFacadeObjectResult>
<IndividualEmailObjects xsi:schemaLocation="http://www.avectra.com/2005/ IndividualEmail.xsd" recordReturn="1">
<IndividualEmailObject>
<eml_key>5f4ef2ae-49fb-414d-aebf-27f569b614f9</eml_key>
</IndividualEmailObject>
</IndividualEmailObjects>
</InsertFacadeObjectResult>
</InsertFacadeObjectResponse>
</soap:Body>
</soap:Envelope>
Sample Request For Multiple Objects in One Exchange
Here is example of sending multiple records in same message exchange. Note that in this example, two email records are being sent to the same cst_key but the second record is to be the primary email address for this individual.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Header>
<m:AuthorizationToken xmlns:m="http://www.avectra.com/2005/">
<m:Token>b328d499-f2dd-44c8-94a1-6d613c05ae7d</m:Token>
</m:AuthorizationToken>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<m:InsertFacadeObject xmlns:m="http://www.avectra.com/2005/">
<m:szObjectName>IndividualEmail</m:szObjectName>
<m:oNode>
<m:IndividualEmails>
<m:IndividualEmail>
<m:eml_address>jroos200@abc.org</m:eml_address>
<m:eml_cst_key>128ac39e-57ae-4bcd-b9c6-07b40405eee7</m:eml_cst_key>
</m:IndividualEmail>
<m:IndividualEmail>
<m:eml_address>jroos300@insp.com</m:eml_address>
<m:eml_cst_key>128ac39e-57ae-4bcd-b9c6-07b40405eee7</m:eml_cst_key>
<m:eml_primary>1</m:eml_primary>
</m:IndividualEmail>
</m:IndividualEmails>
</m:oNode>
</m:InsertFacadeObject>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Sample Response For Multiple Objects in One Exchange
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/03/addressing"
xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soap:Header>
<AuthorizationToken xmlns="http://www.avectra.com/2005/">
<Token>b328d499-f2dd-44c8-94a1-6d613c05ae7d</Token>
</AuthorizationToken>
<wsa:Action>http://www.avectra.com/2005/InsertFacadeObjectResponse</wsa:Action>
<wsa:MessageID>uuid:3a91477a-37da-46ef-869c-b54dce8a7838</wsa:MessageID>
<wsa:RelatesTo>uuid:3b063ba2-1871-4aa1-a5b0-57a4effddee7</wsa:RelatesTo>
<wsa:To>http://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous</wsa:To>
<wsse:Security>
<wsu:Timestamp wsu:Id="Timestamp-9ee04ab5-8966-4d91-8291-bccf29cc4d7e">
<wsu:Created>2006-09-22T13:23:36Z</wsu:Created>
<wsu:Expires>2006-09-22T13:28:36Z</wsu:Expires>
</wsu:Timestamp>
</wsse:Security>
</soap:Header>
<soap:Body>
<InsertFacadeObjectResponse xmlns="http://www.avectra.com/2005/">
<InsertFacadeObjectResult>
<IndividualEmailObjects xsi:schemaLocation="http://www.avectra.com/2005/ IndividualEmail.xsd" recordReturn="2">
<IndividualEmailObject>
<eml_key>4bdb65a9-a375-42d3-aa76-c3529f7b7700</eml_key>
</IndividualEmailObject>
<IndividualEmailObject>
<eml_key>14ce4a47-9ace-44a8-92d9-fbb899cf0eb2</eml_key>
</IndividualEmailObject>
</IndividualEmailObjects>
</InsertFacadeObjectResult>
</InsertFacadeObjectResponse>
</soap:Body>
</soap:Envelope>
Sample Request for User-Defined Custom Object
Where [client_customObjects]/[client_customObject] can be any custom Object defined by the user in netFORUM.
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Header>
<m:AuthorizationToken xmlns:m="http://www.avectra.com/2005/">
<m:Token>72786a3e-d227-4772-bb30-8037ba6b7b26</m:Token>
</m:AuthorizationToken>
</SOAP-ENV:Header>
<SOAP-ENV:Body>
<m:InsertFacadeObject xmlns:m="http://www.avectra.com/2005/">
<m:szObjectName>[client_customObject]</m:szObjectName>
<m:oNode>
<m:[client_customObjects]>
<m:[client_customObject]>
<m:a00_custom_field1>Data for custom field 1</m:a00_custom_field1>
<m:a00_custom_field2>a6e3cb3f-c1cd-4ada-b961-e747db2326f3</m:a00_custom_field2>
</m:[client_customObject]>
</m:[client_customObjects]>
</m:oNode>
</m:InsertFacadeObject>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
FAQ
Change in 2010.01
Q. My InsertFacadeObject and UpdateFacadeObject method calls suddenly stopped working after upgrading to 2010.01. Why?
A. As shown in the sample below, in the <oNode> parameter, you need an outer node (<IndividualEmailObjects>) enclosing an inner node (<IndividualEmailObject>), which encloses the list of elements for each field, as described above. For example:
<ns1:UpdateFacadeObject>
<ns1:szObjectName>IndividualEmail</ns1:szObjectName>
<!-- this parameter is set only for UpdateFacadeObject -->
<ns1:szObjectKey>ebb2bc78-20c3-4fce-bfda-288014ab1f3a</ns1:szObjectKey>
<ns1:oNode>
<ns1:IndividualEmailObjects>
<ns1:IndividualEmailObject>
<ns1:eml_type>Personal</ns1:eml_type>
<ns1:eml_address>zzsopmeone@prodigy.netXX</ns1:eml_address>
<ns1:eml_primary>1</ns1:eml_primary>
</ns1:IndividualEmailObject>
</ns1:IndividualEmailObjects>
</ns1:oNode>
</ns1:UpdateFacadeObject>
Contrast the example above to this example below, without the enclosing outer node <IndividualEmailObjects>. Beginning with 2010.01, the example below will no longer work:
<ns1:UpdateFacadeObject>
<ns1:szObjectName>IndividualEmail</ns1:szObjectName>
<!-- this parameter is set only for UpdateFacadeObject -->
<ns1:szObjectKey>ebb2bc78-20c3-4fce-bfda-288014ab1f3a</ns1:szObjectKey>
<ns1:oNode>
<ns1:IndividualEmailObject>
<ns1:eml_type>Personal</ns1:eml_type>
<ns1:eml_address>zzsomebody@prodigy.netXX</ns1:eml_address>
<ns1:eml_primary>1</ns1:eml_primary>
</ns1:IndividualEmailObject>
</ns1:oNode>
</ns1:UpdateFacadeObject>
Q. Why was this change made?
A. Avectra started shifting integrators to the new syntax around 2007 or earlier, and all code samples, documentation and training have modeled the newer syntax. If you are using the older syntax, then change to the newer syntax before upgrading to 2010.01.
The change was made to support passing multiple nodes within one enclosing outer node to facilitate batch processing in a single request.
Using InsertFacadeObject/UpdateFacadeObject versus specific Methods
See Using InsertFacadeObject/UpdateFacadeObject versus specific Methods for information about when to use a specific insert or update method and when to insert or update a facade object.
Generating code in SQL
This T-SQL syntax shows how to develop XML with a namespace. You can plug this into a soapUI instance.
WITH xmlnamespaces ('uri' AS ns)
SELECT top 10
'ns:cmc_cmt_key' = 'd87dc694-3b9e-4931-99df-890cc38b1723',
'ns:cmc_cst_key' = ind_cst_key,
'ns:cmc_start_date' = '12/01/2013',
'ns:cmc_cxa_key' = cst_cxa_key,
'ns:cmc_cop_key' = 'F9C53D03-41D9-4BF6-803B-CAB432E14832'
FROM co_individual (nolock)
JOIN co_customer (nolock) ON cst_key = ind_cst_key
WHERE ind_cst_key NOT IN (SELECT cmc_cst_key FROM mb_committee_x_customer (nolock) WHERE cmc_cmt_key = 'd87dc694-3b9e-4931-99df-890cc38b1723')
AND cst_cxa_key IS NOT NULL
FOR xml path('ns:mb_committee_x_customerObject'), root('ns:mb_committee_x_customerObjects')
Specify Primary Key in Request
Q. I'm trying to set the primary key for an insert in my request. For example, for the co_action_type table, that's <cat_key>. But I'm getting errors. Is it possible to do this?
A. No, it is not possible to specify a primary key of your choosing. netFORUM will determine this value and return it in the response.