XML Documents

XML Documents are used to retrieve data from the database and return it as an XML document.

See Also

XML Document Templates

Adding Blocks to  XML Documents

Modifying Blocks on  XML Documents

XML Document Fields

Property Definitions

Executable XML Documents

Executable XML documents have an added block with the block type Executable Block.  This block is similar to a report parameter form, but it is activated by a program-constructed URL passed to Xephr®.  The executable block must have a z order less than that of the query block, to ensure that it runs first when it is called.

A program constructs a URL statement and passes it to Xephr to call the XML document entity.  The URL includes the fields in the Executable Block and the values for them as an XML document.

When the Executable Block receives the URL, the insert logic parses out the XML document, determining the value for each field.  The following steps are completed:

• The fields are filled with their matching values from the URL.

• The defaults for fields not provided in the URL are entered.

• The formula fields are processed in the block hierarchy/z order sequence.

• All non-null field values are loaded into temporary global variables in the block hierarchy/z order sequence.  This means that values at the child block level that are dependent upon knowing the parent value will be filled in after the parent value is determined.

• Executes an insert into the tables specified in the block hierarchy/z order sequence.

The XML document's non-executable block is then queried, using the defined key variables as query values.  The XML document is then returned in its normal manner.

The program passing the URL must create the URL in the following manner.  Bolded values are to be replaced with actual values.  When building the XML URL, the entity, blocks, fields, etc must be defined so that the parser can find the fields on the XML block.  This means that the structure of the blocks in the executable block must be strictly followed.

The XEPHR_USER and XEPHR_PWD parameters are only required if the XML document being called requires authentication, such as if the Allow Anonymous property for the XML document is set to false.

http://xephr_virtual_host_location/
exec/
xml_doc_name
?XEPHR_USER=user_name
&XEPHR_PWD=user_password
&XEPHR_NOJVM=Y
&xml=<xml_doc_name>
<xml executable's parent block name (if it has one)>
<xml_executable_block_name>
<FIELD1>value</FIELD1>
<FIELD2>value</FIELD2>
<xml executable child block name (if it has one)>
<FIELD3>value</FIELD3>
<FIELD4>value</FIELD4>
</xml executable child block name (if it has one)>
</xml_executable_block_name>
</xml executable's parent block name (if it has one)>
</xml_doc_name>

For example:

http://ndsdev.nds-i.com/xephr/exec/XORD?XEPHR_USER=user&XEPHR_PWD=pword&XEPHR_NOJVM=Y&xml=<XORD><ODNG><ODNG_DETAIL>
<CUST_NO>100</CUST_NO><CUST_PO>VERBAL</CUST_PO><OEDNG><OEDNG_DETAIL><ITEM_NO>0001</ITEM_NO><QTY_ORDER>10</QTY_ORDER>
</OEDNG_DETAIL></OEDNG><OEDNG><OEDNG_DETAIL><ITEM_NO>0002</ITEM_NO><QTY_ORDER>10</QTY_ORDER></OEDNG_DETAIL>
</OEDNG><OEDNG><OEDNG_DETAIL><ITEM_NO>0003</ITEM_NO><QTY_ORDER>10</QTY_ORDER></OEDNG_DETAIL></OEDNG></ODNG_DETAIL>
</ODNG></XORD>">

When the Executable XML document inserts the rows into the database, the number of rows inserted before a commit is performed is determined by the Executable XML Commit Size property in the Repository Configuration.

Creating XML Documents

1. In the Explorer Tree, expand and select the Group Information object in which you wish to create an XML document.

2. There are options in creating a XML document at this point.

• Right-click on the Group to which you wish to add an XML document, hold your cursor over the Create option, and when the sub-menu is displayed, left-click on the Entity option.  

• Left-click on the [Wizard] button in the Main Toolbar.

• Left-click on the File Menu.  Left-click on the New option.  Left-click on the Wizard option.

• Press Alt+W on the keyboard.

3. The Creating an Entity screen will be displayed.

4. Select the XML entity type by left-clicking on the XML radio button.

5. Click on the Next button on the bottom right of the screen.

6. In the Entity Name field, enter the desired name for the XML document.

7. In the Datasource pop-list, select the desired datasource or (use default).

• Selecting (use default) will allow the XML document to be used with any datasource, and data brought in will be determined by the user's datasource.

7. In the Based On pop-list,select the template on which the new XML document will be based.  Any mutable blocks assigned to the template selected will be copied to the new XML document.  

8. In the Default Mode pop-list, select the view type that will be displayed by default for this XML document.  Choices include Run Report and Parameter Form.

9. Click on the Next button on the bottom right of the screen.

10. The Adding New Block screen will be displayed.

11. See the Adding Blocks to XML Documents section for the next steps.

Modifying XML Documents

1. In the Explorer Tree, expand the Group Information object and select the XML document that you wish to modify.

2. Display the XML document properties.  These will either be displayed in Alphabetical or Logically, depending on the setting of the [Sort Alphabetically/Logically] button.  The following instructions are assuming that the properties are sorted logically.

3. In the Name property, the name that you entered when creating the XML document will be displayed.  It can be changed, if desired.

4. In the Description property, enter a user-defined description for this XML document.  The default is the type of object followed by the XML document name. (i.e. XML:NEW)

5. In the Datasource pop-list, the datasource that you selected when creating the XML document will be displayed.  It can be changed, if desired.
   
   If set to (default), the default for the user's log in will be used when this XML document is displayed.

6. In the Allow Anonymous pop-list, select true if anonymous users should have access to this XML document.  Select false if anonymous users should not have access to this XML document.  

7. The Inherits From pop-list displays the template from which this XML document was created, grayed out.  This value cannot be changed here.

8. In the Default Mode pop-list, select the view type that will be displayed by default for this XML document.  Choices include Run Report and Parameter Form.

9. In the Parameter Screen Width property, enter the width in pixels for the parameter form created for this XML document.

10. In the Parameter Screen Height property, enter the height in pixels for the parameter form created for this XML document.

11. In the Required Roles property, select the roles that are required to run the entity.  When running this entity, the user must have at least one of the roles entered here, or the entity will not run, and the user will be returned to the log in screen.
    
    When you click on this field, a pop-up will be displayed with the available roles in the left side of the pop-up and the roles assigned to the entity on the right side.  
    
    To assign a role to the entity, select the desired role on the left side, and then click on the >> button to move it to the right side.  
    
    To unassign a role, select the desired role on the right side and then click on the << button to move it to the left side.  
    
    When all desired roles have been assigned, click on the Apply button.
    
    The Invalid Access Redirects To property will be displayed to allow you to define the entity that should be displayed for the user if the user does not have one of the required roles entered here.

12. In the Required Globals property, list the global variables that are required to be set in order for the entity to run properly, separated by a line break.  If the entity is run, and some or all of these globals are missing, the entity will not be run.  The format is GLOBAL or, if desired, GLOBAL = VALUE.  
    
    For example, if the global variables ORG_UNIT_ID and EMPNO must be set for the page to run correctly, you would enter
    ORG_UNIT_ID
    EMPNO
    
    If the global variable ORG_UNIT_ID needed to have the value 100, but it didn't matter what the EMPNO value needed to be, you would enter
    ORG_UNIT_ID = 100
    EMPNO

13. In the Accessed via property, enter the entity from which this XML document is generated.  This is an optional property.  For example, if the XML document has certain conditions that must be met on a screen entity before it can be run, the name of the screen entity should be entered here.  This prevents the XML document from being improperly accessed.  

14. In the Invalid Access Redirects To property, enter the entity to which the user will be redirected if this XML document is improperly accessed.  This property is only displayed when the Accessed via property is entered.  
    
    If a user accesses this XML document from an entity other than the one entered in the Accessed via property, instead of opening the XML document, the entity entered in this property will be opened.
    
    If a user that does not have one of the required roles accesses the entity, instead of opening the XML document, the entity defined here is opened.

15. In the Target Host property, enter the server to which the XML document output will be sent for executable XML documents.  For example, if you wanted to pass the output of this XML document to another Xephr server.

16. If an entry is made in the Target Host property, in the Target is Secure property, select true or false to indicate whether the target host is secure and will need to be connected to using SSL.  When this property is set the true, the target host will be connected to using SSL.  

17. If an entry is made in the Target Host property, in the Target Entity property, enter the name of the entity on the target host to which the executable XML output will be passed.

18. If an entry is made in the Target Host property, in the Target User property, enter the user name for connecting to the target host.

19. If an entry is made in the Target User property, in the Target Password property, enter the password for connecting to the target host.  The password will be hidden as a series of fourteen asterisks.

20. In the Results Disposition property, select Return to Caller, FTP, EMail, or Store as File.  
    
    When Return to Caller is selected the results to the query will be returned to the calling browser.  
    When FTP is selected, the results to the query are sent as a file to a defined FTP server.  Additional properties are displayed when FTP is selected.
    When EMail is selected, the results to the query are sent as a file to the defined email addresses.  Additional properties are displayed when EMail is selected.
    When Store as File is selected, the results to the query are sent as a file to the defined location.  Additional properties are displayed when Store as File is selected.

21. If the Results Disposition property is set to FTP, in the FTP Host property, enter the FTP host to which the file will be uploaded.

22. If the Results Disposition property is set to FTP, in the FTP User property, enter the FTP user name for logging into the FTP server.

23. If the Results Disposition property is set to FTP, in the FTP Password property, enter the FTP password for logging into the FTP Server.

24. If the Results Disposition property is set to FTP, in the FTP Binary property, select true or false.  When set to true, the file will be uploaded using binary transfer mode.  When set to false, the file will be uploaded using ASCII transfer mode.

25. If the Results Disposition property is set to FTP, in the FTP Directory property, enter the directory on the FTP server to which the file will be uploaded.

26. If the Results Disposition property is set to FTP, in the FTP Passive property, select true or false.  When set to true, the file will be uploaded to the FTP server using passive mode.

27. If the Results Disposition property is set to EMail, in the EMail From property, enter the email address that will be placed in the From field when the file is emailed.  Global variable references can be entered in this field.

28. If the Results Disposition property is set to EMail, in the EMail Subject property, enter the subject line for the email that will contain the results.   Global variable references can be entered in this field.

29. If the Results Disposition property is set to EMail, in the EMail Message property, enter the message for the email that will contain the results.   Global variable references can be entered in this field.

30. If the Results Disposition property is set to EMail, in the EMail Query property, enter the query that will return the list of email addresses to which the email will be sent.   Global variable references can be entered in this field.

31. If the Results Disposition property is set to Store to File, in the Target Filename property, enter the directory and file name for the file.

32. The Created on property displays the date and time on which the XML document was created and cannot be changed.

33. The Modified on property displays the date and time on which the XML document was last changed and cannot be modified.

34. When all changes have been made, press the [Save] button in the Main Toolbar.

Xephr is a registered trademark of NDS Systems, LC.

Copyright © 2007 NDS Systems LC.