Search

User Manual

GETTING STARTED


MODULES AND PLATFORM


APPENDIX


TUTORIALS & HELPFUL TRICKS


GLOSSARY


STRATEGIC PARTNER LINKS

Sepasoft - MES Modules
Cirrus Link - MQTT Modules

RESOURCES

Inductive University
Ignition Demo Project
Knowledge Base Articles
Forum
IA Support
SDK Documentation
SDK Examples

ALL MANUAL VERSIONS

Ignition 8
Ignition 7.9
Ignition 7.8

Deprecated Pages

Skip to end of metadata
Go to start of metadata


The WebDev module enables you to directly program against the web server inside the Ignition Gateway and systems running Vision Clients. Webpages can be built by hand using a combination of Python programming and static web resources such as images, CSS files, JavaScript files, and HTML files. Likewise, this module allows you to build RESTful web service APIs that allow external systems to interact with the Ignition server. This module follows the normal installation process.

Disclaimer

The WebDev module requires specialized web-programming knowledge. The Inductive Automation support team is unable to provide detailed advice about creating a particular site. Furthermore, they are unable to provide troubleshooting beyond the basic functionality of the module.

Resources

Each type of resource may specify its content type. It is important to specify the correct content type for the contents of the resource. When the WebDev module is installed, a new kind of project resource heading will appear in the Designer's project browser called "Web Dev". Right-clicking on this heading will allow the creation of several new types of project resources:

On this page ...



This feature is new in Ignition version 8.0.7
Click here to check out the other new features
As of 8.0.7 WebDev resources are stored as readable .json and .py files on the Gateway's file system. This is so you can use software to easily diff them (check if they are identical or not) for version control. This does not effect the functionality at all.

  • Python Resource - Python resources are dynamic web resources. Each time a user browses to the URL associated with a Python resource, the script will run and generate a response in the form of a Python dictionary. See Return Value for more details on formatting this response.

  • File Resource - A file resource is a static resource, usually a binary resource such as an image. Note that you will need to re-import a file resource if it has been changed since adding it to WebDev.
  • Text Resource - A text resource is a static resource much like a file resource, except that its contents may be directly edited from within the Ignition Designer. These are useful for static HTML, CSS, and JavaScript files.

Mounted Folder

Mounted Folders are a way to expose a folder from the Gateway's hard drive as a resource endpoint. For example, if the Ignition server had some directories that look liked the following:

Pseudocode - Example Directories
/opt/public/a.jpg
/opt/public/info.html

You can create a Mounted Folder named "assets", and point it to /opt/public/, and then you can access those assets via:

Pseudocode - URL to Mounted Folder
http://host:port/main/system/webdev/projectname/assets/a.jpg

URL Encoding

Be mindful of the filenames in the mounted folder, as URL encoding will need to be used to access the file. For example, if a file named "My file.pdf" was placed in the mounted folder above, the space in the file name would likely be encoded to %20 

http://host:port/main/system/webdev/projectname/assets/My%20file.pdf

Project Resources Folders

If a Mounted Folder is placed in a Project Browser folder, then the endpoint must also include the folder name. For example, if the Mounted Folder named "products" is located in the "images" folder:

The files would be accessible via:

Pseudocode - URL for Mounted Folder with Project Resource Folder
http://host:port/main/system/webdev/projectname/images/products/a.jpg


Right Click Menu 

The Right Click menu is similar to other applications edit menus in that it provides basic copy/paste functionality. Options are described in the following table.

 


OptionDescription
RenameTo rename a resource, select this option then enter a new name.
CutCuts the selected resource onto the clipboard.
CopyCopies the selected resource onto the clipboard. It can then be pasted within the Web Dev make a duplicate.
Copy Path

Copies the path of the selected resource onto the clipboard. For example, "newfile.html".

PastePastes the the selected resource from the clipboard into the selected context.
DeleteDeletes the current selection. This can also be done using the delete key.
ProtectLocks the individual project resource from inside the Designer.

Copy Mounted Path

This feature is new in Ignition version 8.0.7
Click here to check out the other new features

This copies the partial mounted path for the resource into your clipboard. This allows you to easily paste the path into your browser for testing. For example,"/system/webdev/MyProject/newfile.html". You need to add the path to your gateway to the beginning of this string. A full url would look like: "http://10.10.10.150:8088/system/webdev/MyProject/newfile.html"


URL

Each resource will be directly accessible over HTTP and mounted beneath the /main/system/webdev path.

For example, if you created a Text Resource directly beneath the "Web Dev", it would be mounted at:

Pseudocode - Project Resource
http://host:port/main/system/webdev/project/resource_name


Notice that the project name and resource name are part of the path. If your resource is nested inside a folder, it will be part of the path too. For example:

Pseudocode - Folder Resource
http://host:port/main/system/webdev/project/folder_name/resource_name


Web Dev resources may have periods in their name. This means that if you upload an image file, you may include its extension directly in its name so that its path is more natural.  For example, you might name an image resource "my_image.png" so that its URL is:

Pseudocode - Image Resource
http://host:port/main/system/webdev/project/my_image.png


The WebDev module respects the published vs. staging system of Ignition. If your project is set up to have separate staging and published verions, you may access your staging version resources via the URL:

Pseudocode - Staging Version Resource
http://host:port/main/system/webdev_staging/project/resource_name


Requests to the root of your project will attempt to load a resource named "index.html". If no such resource exists, a 404 response code will be returned instead.

Pseudocode - Request to Root Project
http://host:port/main/system/project


Python Resources

Python resources are the heart of the functionality of the WebDev module. These resources are completely dynamic, and can handle all parts of the HTTP protocol, formulating any type of response.

Each time an incoming HTTP request arrives at a URL where a Python resource is mounted, the corresponding Python script will be run. Each Python resource can have a script for each HTTP method. In practice, most Python resources will probably only implement one or two of these, usually doGet or doPost at a minimum. The available methods are as follows:

  • doGet
  • doPost
  • doPut
  • doDelete
  • doHead
  • doOptions
  • doTrace

This feature is new in Ignition version 8.0.7
Click here to check out the other new features

As of 8.0.7 the HTTP method doPatch has been added.


Parameters

Each do* method receives the same two parameters (also called arguments): 'request' and 'session'. 

Request Parameter

The request parameter is a dictionary with information about the incoming web request.

ParameterTypeDescription
context
objectA reference to the Gateway's context object. This provides direct access to the Ignition GatewayContext. More information about this object may be found in the Ignition SDK Programmer's Guide and associated JavaDocs.
data
plain text or raw byte array

The data on the request. If the content type is application/json, it will be a Python structure (list or dictionary). If not, it will either be plain text or a raw byte array.

As of 8.0.7 if the incoming request body was not text, it will be available as a byte array.

postData
string

This parameter is only present for the doPost method, and its value is different based upon the value of the incoming HTTP request's Content-Type header. If the content type is 'application/json', then the request['postData'] will be a Python dictionary structure which is the result of parsing the JSON document that was posted. If the content type starts with 'text/', then the value of request['postData'] will be the text which was posted, as a string.

headers
dictionary

A dictionary of header : value pairs. If multiple values were returned for the same header, values will be in a tuple. The HTTP request headers will be in a dictionary under request['headers']. For example, you could read the User-Agent string with request['headers']['User-Agent'].

params
dictionary

This will be contained in a dictionary accessible via request['params']. 
Any URL parameters such as the following:

Pseudocode - Request Parameter
/main/system/webdev/project/foo?param1=value&param2=other_value

For the given example, request['params'] = {'param1':'value', 'param2':'other_value'}.

remainingPath
string

request['remainingPath'] will be "/bar". Remaining path will be "None" if nothing is found after the resource name. This provides the remaining text after a file resource. If you have a resource called 'foo', and a request is made to:

Pseudocode - Remaining Path
/main/system/webdev/project/foo/bar
remoteAddr
stringReturns the IP address of the client. Gives the remote IP address of the entity that made the web request. Note that this is from the perspective of the web server, and so may not be what you expect due to the effects of things like NAT-ing routers.
remoteHost
stringReturns the fully qualified name of the client. Gives the remote host of the entity that made the web request. Note that this is from the perspective of the web server, and so may not be what you expect due to the effects of things like NAT-ing routers.
scheme
stringThe scheme is available via request['scheme']. The value will be 'http' or 'https'.
servletRequest
objectThe underlying Java HttpServletRequest object. This parameter and the following servletResponse parameter give you direct access to the underlying Java servlet request and response objects.request['context']. This provides direct access to the Ignition GatewayContext. More information about this object may be found in the Ignition SDK developer guide and associated JavaDocs.
servletResponse
objectThe underlying Java HttpServletResponse object.

Session Parameter

The session parameter is a Python dictionary which may be used to hold information which persists across multiple different calls to your Web Dev Python Resource, or across multiple Python Resources. Session management is handled automatically, and this dictionary is created for each new client session. (The client must have cookies enabled for sessions to work). You may place any key-value pairs in the session dictionary you'd like, just make sure that the values are things that can be serialized. All normal Python types (scalar, dictionary, lists, and tuples) are serializable.

If authentication is required, will have a 'user' attribute containing information about the authenticated user, and a 'retryAttempts' attribute with the number of attempts made.


Return Value

Each do* function on a Python resource must generate some sort of HTTP response. This is done by returning a value from the function. The return value should always be a dictionary, in which the following keys are recognized. The keys are listed here in the order they are evaluated. For example, if you have both file and bytes, only file will take effect. The exception is the contentType key, which may be included with any of the other keys to override the default content type.

HTTP ResponseDescription
html
HTML source as a string. The value should be a string, which should be the source of an HTML document. Content type is assumed to be text/html.
json
The value is assumed to either be a string (which should be valid json) or to be a Python object, which will then be encoded into a json string. Content type will be application/json.
file
The value should be a string, which should be the path to a file on the server's filesystem. If no contentType is specified, then the system will attempt to probe the content type from the operating system using java.nio.Files.probeContentType. If the file key is present, but the value points to a file that doesn't exist, an HTTP 404 will be returned.
bytes
 The value should be a byte array. The default content type is application/octet-stream, but you probably want to specify your own.
response
If none of the other keys are present, the system will look for the key response which will be stringified and then returned with the content type text/plain.
contentType
The mime type of the response. Needed only if ambiguous.

If your implementation of the do* function returns a dictionary with none of the above keys, an HTTP 500 error will be returned. However, if you return None, no HTTP 500 error will be returned. In this case, it is assumed that you used therequest['servletResponse'] parameter to directly formulate your HTTP response.


Security Settings

There are several security settings for Python Resources. As of version 8.0.7, all of the settings can be set individually on each resource.

Enabled

If Enabled is checked, then the HTTP Method is enabled. This Enabled checkbox is new for version 8.0.7.

Require HTTPS

If this is checked, then the resource will only be accessible via an SSL connection. If a non-secure HTTP transport is used, the browser will be sent a redirect to the the Gateway's SSL port. The Gateway must have SSL enabled, of course.

Require Authentication

If this is checked, the resource will require authentication before it executes. This uses HTTP BASIC auth, and so should really be combined with the Require HTTPS option so that the credentials are encrypted. The username/password combination sent through the HTTP BASIC authentication headers will then be passed through the chosen User Source. If roles are specified, the user must have at least one of the roles. Specify multiple acceptable roles using a comma separated list. If the credentials are missing, an HTTP 401 will be returned with the WWW-Authenticateheader. If the credentials are present but incorrect, an HTTP 403 will be returned.

If the credentials succeed, the Python resource will execute. In addition, the authenticated user object returned by the User Source will be accessible inside the session object as session['user']. Since the user is stored in session, if the client has cookies enabled, then further requests against the same session will use the stored user object and will not require additional authentication.




  • No labels