Updating the Transaction Requester for retrieve operations

  • Article

The Dynamics GP Service framework uses the eConnect Transaction Requester to retrieve the data for a service document. If your service uses the GetByKey or GetList operations of the Dynamics GP Service framework, you need to use the Transaction Requester to get your document data.

  • For a GetByKey operation, the Transaction Requester retrieves a single document. To specify the document, you must supply the document ID.
  • For a GetList operation, the Transaction Requester retrieves a collection of summary documents that match a specified criteria. The criteria represents a value or range of values that is shared by each document in the collection.

To specify the data to retrieve, the Transaction Requester uses metadata. The metadata describes the data members of your document and provides the information that eConnect uses to construct a query. The query retrieves the data for the specified document from the Dynamics GP database.

The Transaction Requester returns the data it retrieves as a Transaction Requester XML document. The document contains XML nodes that identify each data field and the current value of that data field.

To use the Transaction Requester with a new type of document, you need to provide metadata that describes the data members of your document and summary document. The following steps show how to add metadata for a new document type to the eConnect_Out_Setup table.

Naming document types

One of the key metadata elements is the name. To comply with naming conventions in eConnect and Dynamics GP Services, start the name with "WS". Next, append the type name. Finally, if your are retrieving summary documents, append "GetList". For example, the Transaction Requester metadata for lead documents uses the following names:

WSLead
WSLeadGetList

When you add your document metadata to the eConnect_Out_Setup table, you must use the name for the DOCTYPE parameter.

Adding Transaction Requester SQL stored procedures

To add your document to the Transaction Requester, you need to run the eConnectOutCreate stored procedure. This stored procedure creates a new stored procedure that contains the query that retrieves the data for your document. The eConnectOutCreate stored procedure requires you to supply a name and an output type. Use the name that you created earlier in this section.

The output type specifies whether a single document (GetByKey) or a collection of summary documents (GetList) is being created.

  • If you are adding a Transaction Requester operation for only a GetByKey operation, set the output type parameter to "1".
  • If you are adding Transaction Requester operations for both a GetByKey and a GetList operation, the GetList operation must be added first with the output type parameter "1". Then the GetByKey operation can be added with the output type parameter "2".

Hint: The following section contains a SQL script example that shows how to use the eConnectOutCreate stored procedure.

Adding Transaction Requester metadata

To add a new type of document to the Transaction Requester, complete the following procedure:

  1. Open the Visual Studio solution.

    Use the same project you used for the business objects. Open the solution in Visual Studio.

  2. Add a SQL script file.

    From the Project menu, choose Add SQL Script. In the Add New Item window, click SQL Script in the list of Templates. Enter a name for your script file, and then click Add.

  3. Add statements to the SQL script file.

    Use the SQL script to add entries to the eConnect_Out_Setup table of the company database.

    The following sample script inserts metadata for leads to the eConnect_Out_Setup table. Notice how the first insert statement specifies all the data fields. This metadata describes how to retrieve a single document.

    The second insert statement specifies a smaller number of fields. This metadata describes how to retrieve a summary document. Dynamics GP Services uses summary documents to produce a list of documents.

    Also, notice the name used by the the DOCTYPE parameter of each insert.

    GO

/* Specify the data to retrieve with a GetByKey request / / The GP service platform requires that the DocType start with WS */ INSERT INTO dbo.eConnect_Out_Setup (DOCTYPE,TABLENAME,ALIAS,MAIN,INDEX1,INDEXCNT,DATACNT,DATA1,DATA2,DATA3,DATA4,DATA5,DATA6,DATA7,DATA8,DATA9,DATA10,DATA11,DATA12,DATA13,DATA14,DATA15,DATA16,DATA17,DATA18,DATA19,DATA20,DATA21,DATA22,DATA23) VALUES('WSLead','IG001','Lead',1,'LeadID',1,23,'LeadName','SLPRSNID','CITY','STATE','ZIP','ADDRESS1','ADDRESS2','PHONE1','PHONE2','FAX','LeadBusinessCategory','COUNTRY','CONTACT','PotentialRevenue','QualifiedLead','LeadSource','QualificationDate','LeadPassword','NOTEINDX','Workflow_Approval_Status','Workflow_Priority','Approved_Salesperson_ID','DEX_ROW_TS')

/* Specify the data to retrieve with a GetList request / / The GP service platform requires the the DocType start with WS and end with GetList */ INSERT INTO dbo.eConnect_Out_Setup (DOCTYPE,TABLENAME,ALIAS,MAIN,INDEX1,INDEXCNT,DATACNT,DATA1,DATA2,DATA3,DATA4,DATA5,DATA6) VALUES('WSLeadGetList','IG001','Lead',1,'LeadID',1,6,'LeadName','SLPRSNID','LeadBusinessCategory','QualifiedLead','LeadSource','DEX_ROW_TS') GO

  1. Create the Transaction Requester SQL stored procedures.

    To create the Transaction Requester SQL stored procedures for your document type, run the eConnectOutCreate stored procedure.

    The following script sample creates Transaction Requester SQL stored procedures for leads. Notice how the GetList operation is added first and with an output type of "1". The following statement adds the GetByKey operations and uses an output type of "2".

    /* Create procedures for LeadGetList and LeadGetByKey */

exec eConnectOutCreate 'WSLeadGetList', 1 exec eConnectOutCreate 'WSLead', 2

  1. Save the file.

    In the File menu, choose Save. Once you have completed the script files for eConnect, close the Visual Studio project.