---
title: "MI script Module"
description: "This module provides multiple hooks to run Management Interface commands directly from OpenSIPS script. It supports running both synchronous and asynchronous commands. Depending on the nature of the command (asynchronous or not), and on the way the *mi* command is run from script, the r..."
---

## Admin Guide


### Overview


This module provides multiple hooks to run Management Interface
		commands directly from OpenSIPS script. It supports running
		both synchronous and asynchronous commands. Depending on the
		nature of the command (asynchronous or not), and on the way
		the *mi* command is run from script,
		the returned result is different.


### Values Returned


In case of success, the MI command returns with success.
		If a return variable is provided as parameter,
		a JSON is also stored in the variable provided.


In case of failure of the MI command, JSON-RPC reply error code
		is stored in the *$rc* variable, as a negative
		number. Lower values, such as *-1,-2,-3* can also
		be returned to indicate an internal error. If a return variable is
		provided, it is stored to the error description.


### Dependencies


#### OpenSIPS Modules


The following modules must be loaded before this module:


- *proto_hep module*, in case MI
				tracing is used.


#### External Libraries or Applications


The following libraries or applications must be installed before
		running OpenSIPS with this module loaded:


- *none*


### Exported Parameters


#### pretty_printing (int)


Indicates whether the JSON responses stored in the return
			variable should be pretty-printed or not.


*Default value is "0 - no pretty-printing".*


```c title="Set pretty_printing parameter"
...
modparam("mi_script", "pretty_printing", 1)
...
```


#### trace_destination (string)


Trace destination as defined in the tracing module. Currently
		the only tracing module is **proto_hep**.
		This is where traced mi messages will go.


**WARNING:**A tracing module must be
			loaded in order for this parameter to work. (for example
			**proto_hep**).


*Default value is none(not defined).*


```c title="Set trace_destination parameter"
...
modparam("proto_hep", "trace_id", "[hep_dest]10.0.0.2;transport=tcp;version=3")

modparam("mi_script", "trace_destination", "hep_dest")
...
```


#### trace_bwlist (string)


Filter traced mi commands based on a blacklist or a whitelist.
		**trace_destination** must be defined for
		this parameter to have any purpose. Whitelists can be defined using
		'w' or 'W', blacklists using 'b' or 'B'. The type is separate by the
		actual blacklist by ':'. The mi commands in the list must be separated
		by ','.


Defining a blacklists means all the commands that are not blacklisted
			will be traced. Defining a whitelist means all the commands that are
			not whitelisted will not be traced.
			**WARNING:** One can't define both
			a whitelist and a blacklist. Only one of them is allowed. Defining
			the parameter a second time will just overwrite the first one.


**WARNING:**A tracing module must be
			loaded in order for this parameter to work. (for example
			**proto_hep)**.


*Default value is none(not defined).*


```c title="Set trace_destination parameter"
...
## blacklist ps and which mi commands
## all the other commands shall be traced
modparam("mi_script", "trace_bwlist", "b: ps, which")
...
## allow only sip_trace mi command
## all the other commands will not be traced
modparam("mi_script", "trace_bwlist", "w: sip_trace")
...
```


### Exported Functions


#### mi(command, [ret_var [,params_avp[, vals_avp]]])


Runs an MI command in synchronous mode, blocking
			until a response is available.


*IMPORTANT:* it is highly recommended
			to prevent using this function for tasks that take long
			time, such as reloads, as the function would block until
			the command ends. Moreover, if the running MI
			*command* is configured to run in
			asynchronous mode (such as *t_uac_dlg*
			the command blocks in a busy waiting manner until
			the response is received.


This function can be used in any route.


The function can receive the following parameters:


- *command(string)* - the MI command
					to be run. This can be a single token, representing
					the MI command to run (without parameters), or
					can be followed by several space separated
					parameters (no escaping is handled). Each space
					separated parameter will be passed to the MI
					command as an indexed parameter.
					*NOTE:* named parameters can
					not be specified using this parameter, and you
					will have to use the *params_avp*
					and/or the *vals_avp* parameters
					to specify named commands, in which case this
					parameter will only consist of the MI command.
- *ret_var(var, optional)* - a
					variable used to store the return of the
					MI command execution. In case of success,
					a JSON is stored, otherwise an erorr message.
- *params_avp(avp, optional)* - an
					AVP consisting of all the parameters names that
					will be sent to the MI command. If this parameter
					is used without the *vals_avp*,
					all the values inside the AVP will be passed to the
					MI command as indexed parameters, otherwise as
					named parameters.
					*NOTE:* if this parameter
					is used, the parameters specified in the
					*command* parameter are ignored.
					*NOTE:* the order the
					parameters are passed to the command is the
					same as the one you populate the AVPs (thus
					somehow reversed compared to the way AVPs are
					stored in memory - the first AVP added is the
					first parameter)
- *vals_avp(avp, optional)* - an
					AVP consisting of all the parameters values that
					will be sent to the MI command. This parameter
					only makes sense if the *params_avp*
					is set, and has to contain the same number
					of values as there are parameters.
To specify *array values*, enclose your
					space-separated array elements in the *__array()*
					pseudo-function call.  For example:
					*"__array(HEARTBEAT BACKGROUND_JOB)"*


```c title="mi without params"
...
mi("shm_check");
...
```


```c title="mi with params in command"
...
# this command is similar to the above
mi("cache_remove local password_user1");
...
```


```c title="mi with return"
...
mi("ds_list", $var(ret));
...
```


```c title="mi without return but with indexed params"
...
$avp(params) = "local";
$avp(params) = "password_user1";
mi("cache_remove",,$avp(params));

# the following command is similar to the above
mi("cache_remove local password_user1");
...
```


```c title="mi with return and named parameters"
...
$avp(params) = "callid";
$avp(vals) = "SEARCH_FOR_THIS_CALLID";
$avp(params) = "from_tag";
$avp(vals) = "SEARCH_FOR_THIS_FROM_TAG";
mi("dlg_list", $var(dlg), $avp(params), $avp(vals));
...
```


```c title="mi without return, with an array parameter value"
...
$avp(params) = "freeswitch_url";
$avp(vals) = "fs://:ClueCon@192.168.20.8:8021";
$avp(params) = "events";
$avp(vals) = "__array(HEARTBEAT BACKGROUND_JOB)";
mi("fs_subscribe", , $avp(params), $avp(vals));
...
```


### Exported Asynchronous Functions


#### mi(command, [ret_var [,params_avp[, vals_avp]]])


The function works is more or less the same as its
			synchronous corespondent, except that the MI command
			is run in an asynchronous manner - the process does
			not block to wait for the response, but it continues
			its execution and the MI command is run in an
			asynchronous context.


*NOTE:* currently MI commands run
			asynchronously cannot be traced through hep.


```c title="async mi call usage"
...
xlog("reload starting\n");
async(mi("dr_reload"), after_reload);
...

route[after_reload] {
	xlog("reload completed\n");
}
```
<!-- CONTRIBUTORS -->

### License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0
