doc_how_to.txt

Input to what File: PACKAGE// WEB SERVICE URL HANDLER  
                                          (13 entries)
EDIT WHICH FIELD: ALL// 


Select WEB SERVICE URL HANDLER HTTP VERB: ??
    
   Choose from:
   GET   fileman/dd/{fields}   DD^DDWC001   
   GET   fileman/{file}/{iens}   F^%W0   
   GET   fileman/{file}/{iens}/{field}   FV^%W0   
   GET   filesystem/*   FILESYS^%W0   
   GET   mocha/{type}   MOCHA^%W0   
   GET   r/{routine?.1"%25".32AN}   R^%W0   
   GET   xml   XML^VPRJRSP   
   OPTIONS   rpc/{rpc}   RPCO^%W0   
   POST   MOCHA/ordercheck   MOCHAP^%W0   
   POST   fileman/vals   VALS^DDWC001   
   POST   mocha/{type}   MOCHAP^%W0   
   POST   rpc/{rpc}   RPC^%W0   
   POST   xmlpost   POSTTEST^%W0   
   PUT   r/{routine?.1"%25".32AN}   PR^%W0   
         
        You may enter a new WEB SERVICE URL HANDLER, if you wish
   Choose from: 
          POST       POST
          PUT        PUT
          GET        GET                    
          DELETE     DELETE
          OPTIONS    OPTIONS
          HEAD       HEAD
          TRACE      TRACE
          CONNECT    CONNECT
   
Select WEB SERVICE URL HANDLER HTTP VERB: POST
                                     URI: fileman/fda    
                      EXECUTION ENDPOINT: FDAPOST^DDWC001

  Are you adding 'POST' as a new WEB SERVICE URL HANDLER (the 14TH)? No// Y
  (Yes)
URI: fileman/fda// 
EXECUTION ENDPOINT: FDAPOST^DDWC001// 
AUTHENTICATION REQUIRED?: Y  YES
KEY: 
REVERSE KEY: 
OPTION: 


FDAPOST(ARGS,BODY,RESULT) ; Post an FDA directly to update Fileman Data                                                               
 K ^KBANFDA ZSHOW "*":^KBANFDA
 QUIT ""
 ;
 ;
sakura@icarus:/var2/local/foia201303-2$ curl -k -XPOST https://thebes.smh101.com/fileman/fda -d@-
FDA(1001,"+1,",.01)="ABC"
FDA(1001,"+1,",1)="DEF"
<CTRL-D>

Looking at the result, we see this, and can happily confirm that the server is working.

^KBANFDA("S",1)="FDAPOST+1^DDWC001"
^KBANFDA("S",2)="        Indirection"
^KBANFDA("S",3)="RESPOND+14^VPRJRSP"
^KBANFDA("S",4)="RESPOND+11^VPRJRSP"
^KBANFDA("S",5)="WAIT+36^VPRJREQ"
^KBANFDA("V",1)="%=""71.37.7.7"""
^KBANFDA("V",2)="%WOS=""GT.M"""
^KBANFDA("V",3)="%WTCP=0"
^KBANFDA("V",4)="BODY(1)=""FDA(1001,""""+1,"""",.01)=""""ABC""""FDA(1001,""""+1,"""",1)=""""DEF"""""""
^KBANFDA("V",5)="*HTTPARGS=ARGS"
^KBANFDA("V",6)="HTTPERR=0"
^KBANFDA("V",7)="HTTPLOG=0"
^KBANFDA("V",8)="HTTPLOG(""DT"")=63221"
^KBANFDA("V",9)="HTTPLOG(""ID"")=30"
^KBANFDA("V",10)="HTTPREQ(""header"")=""content-type"""
^KBANFDA("V",11)="HTTPREQ(""header"",""accept"")=""*/*"""
^KBANFDA("V",12)="HTTPREQ(""header"",""content-length"")=48"
^KBANFDA("V",13)="HTTPREQ(""header"",""content-type"")=""application/x-www-form-urlencoded"""
^KBANFDA("V",14)="HTTPREQ(""header"",""host"")=""thebes.smh101.com"""
^KBANFDA("V",15)="HTTPREQ(""header"",""user-agent"")=""curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 lib
          idn/1.23 librtmp/2.3"""
^KBANFDA("V",16)="HTTPREQ(""method"")=""POST"""
^KBANFDA("V",17)="HTTPREQ(""paging"")=""0:999999"""
^KBANFDA("V",18)="HTTPREQ(""path"")=""/fileman/fda"""
^KBANFDA("V",19)="HTTPREQ(""query"")="""""
^KBANFDA("V",20)="HTTPREQ(""store"")=""data"""
^KBANFDA("V",21)="IO(""IP"")=""71.37.7.7"""
^KBANFDA("V",22)="*RESULT=HTTPRSP"
^KBANFDA("V",23)="ROUTINE=""FDAPOST^DDWC001"""
^KBANFDA("V",24)="TCPX="""""

The variable we are most interested in is `BODY`. That contains the posted/putted data. In this case, our two lines seem to have been jumbled together. I actually know from previous experience that this happens with curl when using --data option. Instead, we need to use the --data-binary option so that new lines won't get stripped away.

sakura@icarus:/var2/local/foia201303-2$ curl -k -XPOST https://thebes.smh101.com/fileman/fda --data-binary @-
FDA(1001,"+1,",.01)="ABC"
FDA(1001,"+1,",1)="DEF"

Now, we see that the data printed out as follows, which is much more to our liking.

^KBANFDA("V",4)="BODY(1)=""FDA(1001,""""+1,"""",.01)=""""ABC""""""_$C(10)_""FDA(1001,""""+1,"""",1)=""""DEF""""""_$C(10)"

Now, let's edit the routine to parse the FDA:

FDAPOST(ARGS,BODY,RESULT) ; Post an FDA directly to update Fileman Data
 N PARSED ; Parsed array which stores each line on a separate node.
 D PARSE10^VPRJRUT(.BODY,.PARSED) ; Parser                                                                                            
 K ^KBANFDA M ^KBANFDA=PARSED                                                                                                         
 QUIT ""
 ;

Now, here's the result:
GTM>zwrite ^KBANFDA
^KBANFDA(1)="FDA(1001,""+1,"",.01)=""ABC"""
^KBANFDA(2)="FDA(1001,""+1,"",1)=""DEF"""
^KBANFDA(3)=""

This is actually good enough to help us write the rest of the code.

Let's do it, assuming we are using FDA as the variable:

 FDAPOST(ARGS,BODY,RESULT) ; Post an FDA directly to update Fileman Data
  N PARSED ; Parsed array which stores each line on a separate node.
  D PARSE10^VPRJRUT(.BODY,.PARSED) ; Parser
  N I S I="" 
  F  S I=$O(PARSED(I)) Q:I=""  D                                                                                                       
  . I PARSED(I)'="" S @PARSED(I)
  D UPDATE^DIE("",$NA(FDA))
  QUIT "" <-- Must quit with a value for any PUT or POST requests. See later for why.

At the same time, on this instance, we need to make sure we are making a valid FDA. Here's the condensed DD...

CONDENSED DATA DICTIONARY---BACH WERKE VERZEICHNIS FILE (#1001) 

STORED IN: ^BWV(                                          FEB 3,2014  PAGE 1
--------------------------------------------------------------------------------

                                                  FILE SECURITY
                                   DD SECURITY    :       DELETE SECURITY: 
                                   READ SECURITY  :       LAYGO SECURITY : 
                                   WRITE SECURITY : 
CROSS REFERENCED BY:
      BWV NUMBER(B) 


                                 FILE STRUCTURE

FIELD     FIELD
NUMBER    NAME

.01       BWV NUMBER (RFJ7), [0;1]
.02       WORK TITLE (FJ200), [0;2]
.03       YEAR COMPOSED (NJ4,0), [0;3]
1         INSTRUMENT (Multiple-1001.01), [1;0]
          .01  INSTRUMENT (MFJ100), [0;1]
          .02  NUMBER (NJ2,0), [0;2]
2.1       KEY (P1002), [2;1]

Now, let's go ahead and file the data with curl.
curl -k -XPOST https://thebes.smh101.com/fileman/fda --data-binary @-
FDA(1001,"+1,",.01)=565
FDA(1001,"+1,",.02)="Toccata and Fugue"
FDA(1001,"+1,",.03)=1780
<CTRL-D><CTRL-D>

Now, let's check our handy work:

Output from what File: BACH WERKE VERZEICHNIS//   (6 entries)
Select BACH WERKE VERZEICHNIS BWV NUMBER: 565       Toccata and Fugue     
Another one: 
Standard Captioned Output? Yes//   (Yes)
Include COMPUTED fields:  (N/Y/R/B): NO//  - No record number (IEN), no Computed Fields

BWV NUMBER: 565                         WORK TITLE: Toccata and Fugue
  YEAR COMPOSED: 1780

## Passing flags
We need to support passing flags to the updater call. We need to decide a format--Since we are not passing in JSON using this call, we cannot pass it as part of the JSON. What we can do is to obtain it from the URL as a query variable.
So, a url like https://thebes.smh101.com/fileman/fda?flags=E may do the trick. Supporting that in our code is easy.

Notice that in our code, the FLAGS variable is obtained from ARGS("flags"), which is where MWS puts the query parameter from the URL.

I made a consious decision for future compatibility not to restrict which flags can go into the updater. If there is an error, we will leave it to Fileman to handle that. But we will deal with that in a moment.

FDAPOST(ARGS,BODY,RESULT) ; Post an FDA directly to update Fileman Data
 N PARSED ; Parsed array which stores each line on a separate node.
 D PARSE10^VPRJRUT(.BODY,.PARSED) ; Parse by CR/LF
 ;
 ; Process flags
 N FLAGS S FLAGS=""
 I $D(ARGS("flags")) S FLAGS=$$UP^VPRJRUT(ARGS("flags"))
 ;                                                                                                                                    
 ; Set FDA
 N I S I="" 
 F  S I=$O(PARSED(I)) Q:I=""  D
 . I PARSED(I)'="" S @PARSED(I)
 ;
 D UPDATE^DIE(FLAGS,$NA(FDA))
 QUIT ""

Now, to test it using curl again. Before we do that, we have to find an appropriate experiment.

Remember we had in our data dictionary a field named KEY that was a pointer? Normally, we will only be able to file it ONLY IF we supply it with a number, unless we supply the external form, which is the key name. Let's file our Toccata and Fugue in D minor BWV 565.

GTM>ZWRITE ^MusicKey
^MusicKey(0)="MUSICAL KEY^1002^5^5"
^MusicKey(1,0)="F MAJOR"
^MusicKey(2,0)="G MAJOR"
^MusicKey(3,0)="D MAJOR"
^MusicKey(4,0)="B FLAT MAJOR"
^MusicKey(5,0)="D MINOR"
^MusicKey("B","B FLAT MAJOR",4)=""
^MusicKey("B","D MAJOR",3)=""
^MusicKey("B","D MINOR",5)=""
^MusicKey("B","F MAJOR",1)=""
^MusicKey("B","G MAJOR",2)=""

sakura@icarus:/var2/local/foia201303-2$ curl -k -XPOST https://thebes.smh101.com/fileman/fda?flags=E --data-binary @-
FDA(1001,"+1,",.01)=565
FDA(1001,"+1,",.02)="Toccata and Fugue"
FDA(1001,"+1,",.03)=1680
FDA(1001,"+1,",2.1)="D MINOR"

And now let's check:

Select BACH WERKE VERZEICHNIS BWV NUMBER: 565
     1   565       Toccata and Fugue     
     2   565       Toccata and Fugue     D MINOR
CHOOSE 1-2: 2  565     Toccata and Fugue     D MINOR
Another one: 
Standard Captioned Output? Yes//   (Yes)
Include COMPUTED fields:  (N/Y/R/B): NO//  - No record number (IEN), no Computed Fields

BWV NUMBER: 565                         WORK TITLE: Toccata and Fugue
  YEAR COMPOSED: 1680                   KEY: D MINOR

That's great. The easy part of the coding is done.

A required part of a RESTful interface is to return the URL where the created data can be accessed. This can be easily done. That's the purpose of the extrinsic return which we left as an empty string up till now.

Run the curl command again, but this time add a `-i` to tell it to print out the return headers. Here they are:

sakura@icarus:/var2/local/foia201303-2$ curl -k -i -XPOST https://thebes.smh101.com/fileman/fda?flags=E --data-binary @-
FDA(1001,"+1,",.01)=565
FDA(1001,"+1,",.02)="Toccata and Fugue"
FDA(1001,"+1,",.03)=1680
FDA(1001,"+1,",2.1)="D MINOR"
HTTP/1.1 200 OK
Date: Wed, 05 Feb 2014 22:02:34 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 0

Let's make the change to return a url.

FDAPOST(ARGS,BODY,RESULT) ; Post an FDA directly to update Fileman Data
 N PARSED ; Parsed array which stores each line on a separate node.
 D PARSE10^VPRJRUT(.BODY,.PARSED) ; Parse by CR/LF
 ;
 ; Process flags
 N FLAGS S FLAGS=""
 I $D(ARGS("flags")) S FLAGS=$$UP^VPRJRUT(ARGS("flags"))
 ;
 ; Set FDA
 N I S I="" 
 F  S I=$O(PARSED(I)) Q:I=""  D
 . I PARSED(I)'="" S @PARSED(I)
 ;
 N IEN,FILE
 S FILE=$O(FDA(""))
 D UPDATE^DIE(FLAGS,$NA(FDA),$NA(IEN))
 QUIT "/fileman/"_FILE_"/"_IEN(1)                                                                                                     

---

Let's try it now.

sakura@icarus:/var2/local/foia201303-2$ curl -k -i -XPOST https://thebes.smh101.com/fileman/fda?flags=E --data-binary @-
FDA(1001,"+1,",.01)=565
FDA(1001,"+1,",.02)="Toccata and Fugue"
FDA(1001,"+1,",.03)=1680
FDA(1001,"+1,",2.1)="D MINOR"
HTTP/1.1 201 Created
Date: Wed, 05 Feb 2014 22:22:52 GMT
Location: https://thebes.smh101.com/fileman/1001/10
Content-Type: application/json; charset=utf-8
Content-Length: 0

We got the location header back telling us where the posted data is located. And let's try that URL:
sakura@icarus:/var2/local/foia201303-2$ curl -k https://thebes.smh101.com/fileman/1001/10
{"BWV NUMBER":565,"KEY":"D MINOR","WORK TITLE":"Toccata and Fugue","YEAR COMPOSED":1680}

Perfect!

---

## Handling errors
Right now we return with an HTTP success code whether the updater succeeded or not.

We actually need to check whether fileman actually succeeded. We need to check the variable DIERR and return what's in TMP("DIERR",$J) as the error message.

In my testing, it turned out that that format returned by Fileman is difficult to represent in JSON:

^KBANERR("DIERR",16482,1)=701
^KBANERR("DIERR",16482,1,"PARAM",0)=3
^KBANERR("DIERR",16482,1,"PARAM",3)=1880
^KBANERR("DIERR",16482,1,"PARAM","FIELD")=.03
^KBANERR("DIERR",16482,1,"PARAM","FILE")=1001
^KBANERR("DIERR",16482,1,"TEXT",1)="The value '1880' for field YEAR COMPOSED in file BACH WERKE VERZEICHNIS is not valid."
^KBANERR("DIERR",16482,"E",701,1)=""

So after some fiddling and addition of an expanded error format to MWS, this is the new code.

FDAPOST(ARGS,BODY,RESULT) ; Post an FDA directly to update Fileman Data
 N PARSED ; Parsed array which stores each line on a separate node.
 D PARSE10^VPRJRUT(.BODY,.PARSED) ; Parse by CR/LF
 ;                                                                                                                                    
 ; Process flags
 N FLAGS S FLAGS=""
 I $D(ARGS("flags")) S FLAGS=$$UP^VPRJRUT(ARGS("flags"))
 ;
 ; Set FDA
 N I S I="" 
 F  S I=$O(PARSED(I)) Q:I=""  D
 . I PARSED(I)'="" S @PARSED(I)
 ;
 N DIERR
 N IEN,FILE
 S FILE=$O(FDA(""))
 D UPDATE^DIE(FLAGS,$NA(FDA),$NA(IEN))
 ;
 I $D(DIERR) DO  QUIT ""
 . N ERROR
 . N I S I=0  F  S I=$O(^TMP("DIERR",$J,I)) Q:'I  D
 . . M ERROR("PARAM")=^TMP("DIERR",$J,I,"PARAM")
 . . S ERROR("PARAM","CODE")=^TMP("DIERR",$J,I)
 . . M ERROR("TEXT")=^TMP("DIERR",$J,I,"TEXT")
 . . D SETERROR^VPRJRUT(400,,.ERROR)
 . D CLEAN^DILF ; Remove Fileman temp vars
 ;
 QUIT "/fileman/"_FILE_"/"_IEN(1)

To test it, try this:
sakura@icarus:/tmp$ curl -ks -XPOST https://thebes.smh101.com/fileman/fda?flags=E --data-binary @- | python -mjson.tool
FDA(1001,"+1,",.01)=565
FDA(1001,"+1,",.02)="Toccata and Fugue"
FDA(1001,"+1,",.03)=1880
FDA(1001,"+1,",2.1)="D MINOR"
<CTRL-D><CTRL-D>
{
    "apiVersion": "1.0", 
    "error": {
        "code": 400, 
        "errors": [
            {
                "PARAM": {
                    "0": 3, 
                    "3": 1880, 
                    "CODE": 701, 
                    "FIELD": ".03", 
                    "FILE": 1001
                }, 
                "TEXT": [
                    "The value '1880' for field YEAR COMPOSED in file BACH WERKE VERZEICHNIS is not valid."
                ]
            }
        ], 
        "message": "Bad Request", 
        "request": "POST /fileman/fda flags=E"
    }
}